This version of GitHub Enterprise will be discontinued on This version of GitHub Enterprise was discontinued on 2020-08-20. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Article version: Enterprise Server 2.18

OAuth Authorizations

In this article

Deprecation Notice: The token attribute is deprecated in some OAuth Authorizations API responses:

  • List your authorizations
  • Get a single authorization
  • Get-or-create an authorization for a specific app - token is still returned for "create"
  • Get-or-create an authorization for a specific app and fingerprint - token is still returned for "create"
  • Update an existing authorization

To reduce the impact of removing the token value, the OAuth Authorizations API now includes a new request attribute (fingerprint), three new response attributes (token_last_eight, hashed_token, and fingerprint), and the Get or create an authorization for a specific app and fingerprint endpoint.

This functionality became the default for all requests on April 20, 2015. Please see the blog post for full details.

You can use this API to manage the access OAuth applications have to your account. You can only access this API via Basic Authentication using your username and password, not tokens.

If you or your users have two-factor authentication enabled, make sure you understand how to work with two-factor authentication.

List your grants

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return ["repo", "user"].

get /applications/grants

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/grants
JavaScript (@octokit/core.js)
await octokit.request('GET /applications/grants')

Default response

Status: 200 OK
[
  {
    "id": 1,
    "url": "https://api.github.com/applications/grants/1",
    "app": {
      "url": "http://my-github-app.com",
      "name": "my github app",
      "client_id": "abcde12345fghij67890"
    },
    "created_at": "2011-09-06T17:26:27Z",
    "updated_at": "2011-09-06T20:39:23Z",
    "scopes": [
      "public_repo"
    ]
  }
]

get /applications/grants/{grant_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

grant_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/grants/42
JavaScript (@octokit/core.js)
await octokit.request('GET /applications/grants/{grant_id}', {
  grant_id: 42
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/applications/grants/1",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "created_at": "2011-09-06T17:26:27Z",
  "updated_at": "2011-09-06T20:39:23Z",
  "scopes": [
    "public_repo"
  ]
}

Delete a grant

Deleting an OAuth application's grant will also delete all OAuth tokens associated with the application for your user. Once deleted, the application has no access to your account and is no longer listed on the application authorizations settings screen within GitHub.

delete /applications/grants/{grant_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

grant_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/grants/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /applications/grants/{grant_id}', {
  grant_id: 42
})

Default Response

Status: 204 No Content

Revoke a grant for an application

OAuth application owners can revoke a grant for their OAuth application and a specific user. You must use Basic Authentication for this method, where the username is the OAuth application client_id and the password is its client_secret. You must also provide a valid token as :access_token and the grant for the token's owner will be deleted.

Deleting an OAuth application's grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user's account and will no longer be listed on the application authorizations settings screen within GitHub.

delete /applications/{client_id}/grants/{access_token}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
access_token string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/CLIENT_ID/grants/ACCESS_TOKEN
JavaScript (@octokit/core.js)
await octokit.request('DELETE /applications/{client_id}/grants/{access_token}', {
  client_id: 'client_id',
  access_token: 'access_token'
})

Default Response

Status: 204 No Content

Check an authorization

OAuth applications can use a special API method for checking OAuth token validity without running afoul of normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use Basic Authentication when accessing it, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

get /applications/{client_id}/tokens/{access_token}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
access_token string path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/CLIENT_ID/tokens/ACCESS_TOKEN
JavaScript (@octokit/core.js)
await octokit.request('GET /applications/{client_id}/tokens/{access_token}', {
  client_id: 'client_id',
  access_token: 'access_token'
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678",
  "user": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Reset an authorization

OAuth applications can use this API method to reset a valid OAuth token without end user involvement. Applications must save the "token" property in the response, because changes take effect immediately. You must use Basic Authentication when accessing it, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

post /applications/{client_id}/tokens/{access_token}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
access_token string path

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/CLIENT_ID/tokens/ACCESS_TOKEN
JavaScript (@octokit/core.js)
await octokit.request('POST /applications/{client_id}/tokens/{access_token}', {
  client_id: 'client_id',
  access_token: 'access_token'
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678",
  "user": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Revoke an authorization for an application

OAuth application owners can revoke a single token for an OAuth application. You must use Basic Authentication for this method, where the username is the OAuth application client_id and the password is its client_secret.

delete /applications/{client_id}/tokens/{access_token}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
access_token string path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/applications/CLIENT_ID/tokens/ACCESS_TOKEN
JavaScript (@octokit/core.js)
await octokit.request('DELETE /applications/{client_id}/tokens/{access_token}', {
  client_id: 'client_id',
  access_token: 'access_token'
})

Default Response

Status: 204 No Content

get /authorizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations
JavaScript (@octokit/core.js)
await octokit.request('GET /authorizations')

Default response

Status: 200 OK
[
  {
    "id": 2,
    "url": "https://enterprise.octocat.com/api/v3/authorizations/2",
    "app": {
      "name": "My personal access token",
      "url": "https://developer.github.com/enterprise/v3/enterprise-admin/users/#list-personal-access-tokens",
      "client_id": "00000000000000000000"
    },
    "token": "",
    "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
    "token_last_eight": "848f9f8a",
    "note": "My personal access token",
    "note_url": null,
    "created_at": "2019-04-24T21:49:02Z",
    "updated_at": "2019-04-24T21:49:02Z",
    "scopes": [
      "admin:business",
      "admin:gpg_key",
      "admin:org",
      "admin:org_hook",
      "admin:pre_receive_hook",
      "admin:public_key",
      "admin:repo_hook",
      "delete_repo",
      "gist",
      "notifications",
      "repo",
      "user",
      "write:discussion"
    ],
    "fingerprint": null
  }
]

Create a new authorization

Creates OAuth tokens using Basic Authentication. If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "Working with two-factor authentication."

You can use this endpoint to create multiple OAuth tokens instead of implementing the web flow.

To create tokens for a particular OAuth application using this endpoint, you must authenticate as the user you want to create an authorization for and provide the app's client ID and secret, found on your OAuth application's settings page. If your OAuth application intends to create multiple tokens for one user, use fingerprint to differentiate between them.

You can also create tokens on GitHub from the personal access tokens settings page. Read more about these tokens in the GitHub Help documentation.

post /authorizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

scopes array of strings body

A list of scopes that this authorization is in.

note string body

Required. A note to remind you what the OAuth token is for. Tokens not associated with a specific OAuth application (i.e. personal access tokens) must have a unique note.

note_url string body

A URL to remind you what app the OAuth token is for.

client_id string body

The 20 character OAuth app client key for which to create the token.

client_secret string body

The 40 character OAuth app client secret for which to create the token.

fingerprint string body

A unique string to distinguish an authorization from others created for the same client ID and user.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations \
  -d '{"note":"note"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /authorizations', {
  note: 'note'
})

Default response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Get-or-create an authorization for a specific app

Creates a new authorization for the specified OAuth application, only if an authorization for that application doesn't already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. It returns the user's existing authorization for the application if one is present. Otherwise, it creates and returns a new one.

If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "Working with two-factor authentication."

put /authorizations/clients/{client_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
client_secret string body

Required. The 40 character OAuth app client secret associated with the client ID specified in the URL.

scopes array of strings body

A list of scopes that this authorization is in.

note string body

A note to remind you what the OAuth token is for.

note_url string body

A URL to remind you what app the OAuth token is for.

fingerprint string body

A unique string to distinguish an authorization from others created for the same client and user. If provided, this API is functionally equivalent to Get-or-create an authorization for a specific app and fingerprint.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations/clients/CLIENT_ID \
  -d '{"client_secret":"client_secret"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /authorizations/clients/{client_id}', {
  client_id: 'client_id',
  client_secret: 'client_secret'
})

Response if returning an existing token

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": ""
}

Default response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Get-or-create an authorization for a specific app and fingerprint

This method will create a new authorization for the specified OAuth application, only if an authorization for that application and fingerprint do not already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. fingerprint is a unique string to distinguish an authorization from others created for the same client ID and user. It returns the user's existing authorization for the application if one is present. Otherwise, it creates and returns a new one.

If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "Working with two-factor authentication."

put /authorizations/clients/{client_id}/{fingerprint}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

client_id string path
fingerprint string path
client_secret string body

Required. The 40 character OAuth app client secret associated with the client ID specified in the URL.

scopes array of strings body

A list of scopes that this authorization is in.

note string body

A note to remind you what the OAuth token is for.

note_url string body

A URL to remind you what app the OAuth token is for.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations/clients/CLIENT_ID/FINGERPRINT \
  -d '{"client_secret":"client_secret"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /authorizations/clients/{client_id}/{fingerprint}', {
  client_id: 'client_id',
  fingerprint: 'fingerprint',
  client_secret: 'client_secret'
})

Response if returning an existing token

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Default response

Status: 201 Created
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abcdefgh12345678",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

get /authorizations/{authorization_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

authorization_id integer path

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations/42
JavaScript (@octokit/core.js)
await octokit.request('GET /authorizations/{authorization_id}', {
  authorization_id: 42
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

Update an existing authorization

If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "Working with two-factor authentication."

You can only send one of these scope keys at a time.

patch /authorizations/{authorization_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

authorization_id integer path
scopes array of strings body

Replaces the authorization scopes with these.

add_scopes array of strings body

A list of scopes to add to this authorization.

remove_scopes array of strings body

A list of scopes to remove from this authorization.

note string body

A note to remind you what the OAuth token is for. Tokens not associated with a specific OAuth application (i.e. personal access tokens) must have a unique note.

note_url string body

A URL to remind you what app the OAuth token is for.

fingerprint string body

A unique string to distinguish an authorization from others created for the same client ID and user.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations/42 \
  -d '{"scopes":["scopes"]}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /authorizations/{authorization_id}', {
  authorization_id: 42,
  scopes: [
    'scopes'
  ]
})

Default response

Status: 200 OK
{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "",
  "token_last_eight": "12345678",
  "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
  "app": {
    "url": "http://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "http://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "jklmnop12345678"
}

delete /authorizations/{authorization_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

authorization_id integer path

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://{hostname}/authorizations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /authorizations/{authorization_id}', {
  authorization_id: 42
})

Default Response

Status: 204 No Content

Ask a human

Can't find what you're looking for?

Contact us