OAuth Authorizations

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"].

Parameters

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 a single grant

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

List your authorizations

Parameters

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.

Parameters

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."

Parameters

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."

Parameters

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 a single authorization

Parameters

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.

Parameters

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 an authorization

Parameters

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