Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Esta versão do GitHub Enterprise será descontinuada em Esta versão do GitHub Enterprise foi descontinuada em 2020-08-20. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

Versão do artigo: Enterprise Server 2.18

OAuth Authorizations

Neste artigo

Aviso de Depreciação: O atributo token está obsoleto em algumas respostas da API de Autorizações OAuth:

  • Listar suas autorizações
  • Obter uma autorização única
  • Obter ou criar uma autorização para um aplicativo específico - token ainda é devolvido para "criar"
  • Obter ou criar uma autorização para um aplicativo específico e impressão digital - token ainda é devolvido para "criar"
  • Atualizar uma autorização existente

Para reduzir o impacto de remover o valor de token, a API de Autorização de OAuth inclui agora um novo atributo de solicitação (fingerprint), três novos atributos de resposta (token_last_eight, hashed_token, and fingerprint), e também o ponto de extremidade Get or create an authorization for a specific app and fingerprint.

Esta funcionalidade tornou-se o padrão para todas as solicitações no dia 20 de abril de 2015. Por favor, veja the blog post para maiores detalhes.

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

Parâmetros

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.

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

grant_id integer path

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

grant_id integer path

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

client_id string path
access_token string path

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

client_id string path
access_token string path

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

client_id string path
access_token string path

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

client_id string path
access_token string path

Amostras de código

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

Parâmetros

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.

Amostras de código

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

Parâmetros

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.

Amostras de código

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}

Parâmetros

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.

Amostras de código

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}

Parâmetros

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.

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

authorization_id integer path

Amostras de código

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}

Parâmetros

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.

Amostras de código

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}

Parâmetros

Name Type In Description
accept string header

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

authorization_id integer path

Amostras de código

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

Pergunte a uma pessoa

Não consegue encontrar o que procura?

Entrar em contato