- Notifications
You must be signed in to change notification settings - Fork46
GitHub API token authentication for browsers and Node.js
License
octokit/auth-token.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
GitHub API token authentication for browsers and Node.js
@octokit/auth-token is the simplest ofGitHub’s authentication strategies.
It is useful if you want to support multiple authentication strategies, as it’s API is compatible with its sibling packages forbasic,GitHub App andOAuth app authentication.
- Usage
createTokenAuth(token) optionsauth()- Authentication object
auth.hook(request, route, options)orauth.hook(request, options)- Find more information
- License
| Browsers | Load <scripttype="module">import{createTokenAuth}from"https://esm.sh/@octokit/auth-token";</script> |
|---|---|
| Node | Install with import{createTokenAuth}from"@octokit/auth-token"; |
constauth=createTokenAuth("ghp_PersonalAccessToken01245678900000000");constauthentication=awaitauth();// {// type: 'token',// token: 'ghp_PersonalAccessToken01245678900000000',// tokenType: 'oauth'// }
ThecreateTokenAuth method accepts a single argument of type string, which is the token. The passed token can be one of the following:
- Personal access token
- OAuth access token
- GITHUB_TOKEN provided to GitHub Actions
- Installation access token (server-to-server)
- User authentication for installation (user-to-server)
Examples
// Personal access token or OAuth access tokencreateTokenAuth("ghp_PersonalAccessToken01245678900000000");// {// type: 'token',// token: 'ghp_PersonalAccessToken01245678900000000',// tokenType: 'oauth'// }// Installation access token or GitHub Action tokencreateTokenAuth("ghs_InstallallationOrActionToken00000000");// {// type: 'token',// token: 'ghs_InstallallationOrActionToken00000000',// tokenType: 'installation'// }// Installation access token or GitHub Action tokencreateTokenAuth("ghu_InstallationUserToServer000000000000");// {// type: 'token',// token: 'ghu_InstallationUserToServer000000000000',// tokenType: 'user-to-server'// }
Theauth() method has no options. It returns a promise which resolves with the the authentication object.
| name | type | description |
|---|---|---|
type | string | "token" |
token | string | The provided token. |
tokenType | string | Can be either"oauth" for personal access tokens and OAuth tokens,"installation" for installation access tokens (includesGITHUB_TOKEN provided to GitHub Actions),"app" for a GitHub App JSON Web Token, or"user-to-server" for a user authentication token through an app installation. |
auth.hook() hooks directly into the request life cycle. It authenticates the request using the provided token.
Therequest option is an instance of@octokit/request. Theroute/options parameters are the same as for therequest() method.
auth.hook() can be called directly to send an authenticated request
const{data:authorizations}=awaitauth.hook(request,"GET /authorizations",);
Or it can be passed as option torequest().
constrequestWithAuth=request.defaults({request:{hook:auth.hook,},});const{data:authorizations}=awaitrequestWithAuth("GET /authorizations");
auth() does not send any requests, it only transforms the provided token string into an authentication object.
Here is a list of things you can do to retrieve further information
Note that this does not work for installations. There is no way to retrieve permissions based on an installation access tokens.
constTOKEN="ghp_PersonalAccessToken01245678900000000";constauth=createTokenAuth(TOKEN);constauthentication=awaitauth();constresponse=awaitrequest("HEAD /");constscopes=response.headers["x-oauth-scopes"].split(/,\s+/);if(scopes.length){console.log(`"${TOKEN}" has${scopes.length} scopes enabled:${scopes.join(", ")}`,);}else{console.log(`"${TOKEN}" has no scopes enabled`);}
constTOKEN="ghp_PersonalAccessToken01245678900000000";constauth=createTokenAuth(TOKEN);constauthentication=awaitauth();constresponse=awaitrequest("HEAD /");constclientId=response.headers["x-oauth-client-id"];if(clientId){console.log(`"${token}" is an OAuth token, its app’s client_id is${clientId}.`,);}else{console.log(`"${token}" is a personal access token`);}
Note that thepermissions key is not set when authenticated using an installation access token.
constTOKEN="ghp_PersonalAccessToken01245678900000000";constauth=createTokenAuth(TOKEN);constauthentication=awaitauth();constresponse=awaitrequest("GET /repos/{owner}/{repo}",{owner:"octocat",repo:"hello-world",});console.log(response.data.permissions);// {// admin: true,// push: true,// pull: true// }
Both OAuth and installation access tokens can be used for git operations. However, when using with an installation,the token must be prefixed withx-access-token.
This example is using theexeca package to run agit push command.
constTOKEN="ghp_PersonalAccessToken01245678900000000";constauth=createTokenAuth(TOKEN);const{ token, tokenType}=awaitauth();consttokenWithPrefix=tokenType==="installation" ?`x-access-token:${token}` :token;constrepositoryUrl=`https://${tokenWithPrefix}@github.com/octocat/hello-world.git`;const{ stdout}=awaitexeca("git",["push",repositoryUrl]);console.log(stdout);
About
GitHub API token authentication for browsers and Node.js
Topics
Resources
License
Code of conduct
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.