Skip to main content
Manja / GitHub

Get-or-create an authorization for a specific app

Deprecated

**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/). **Warning:** Apps must use the [web application flow](https://docs.github.com/[email protected]/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api). 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](https://docs.github.com/[email protected]/rest/overview/other-authentication-methods#working-with-two-factor-authentication)." **Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).

PUT/authorizations/clients/{client_id}
Source
github-v3-rest.json
Revision
f5f067c1e6f6
Active snapshot
85e53e3d0d65

Request

Path Parameters
client_id string
required

The client ID of your GitHub app.

Body Params
required
application/jsonobject
client_secret string
required

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

maxLength:40

fingerprint string
optional

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

note string
optional

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

Example: Update all gems

note_url string
optional

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

scopes array[string]
optionalnullable

A list of scopes that this authorization is in.

Example:
[
  "public_repo",
  "user"
]

Responses

application/json Authorization object

if returning an existing token

Headers
Location string

Example: https://api.github.com/authorizations/1

app object
required
client_id string
required
name string
required
url string<uri>
required
created_at string<date-time>
required
fingerprint string
requirednullable
hashed_token string
requirednullable
id integer
required
installation Scoped Installation object
optionalnullable
account Simple User object
required

Simple User

avatar_url string<uri>
required

Example: https://github.com/images/error/octocat_happy.gif

email string
optionalnullable
events_url string
required

Example: https://api.github.com/users/octocat/events{/privacy}

followers_url string<uri>
required

Example: https://api.github.com/users/octocat/followers

following_url string
required

Example: https://api.github.com/users/octocat/following{/other_user}

gists_url string
required

Example: https://api.github.com/users/octocat/gists{/gist_id}

gravatar_id string
requirednullable

Example: 41d064eb2195891e12d0413f63227ea7

html_url string<uri>
required

Example: https://github.com/octocat

id integer
required

Example: 1

login string
required

Example: octocat

name string
optionalnullable
node_id string
required

Example: MDQ6VXNlcjE=

organizations_url string<uri>
required

Example: https://api.github.com/users/octocat/orgs

received_events_url string<uri>
required

Example: https://api.github.com/users/octocat/received_events

repos_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

site_admin boolean
required
starred_at string
optional

Example: "2020-07-09T00:17:55Z"

starred_url string
required

Example: https://api.github.com/users/octocat/starred{/owner}{/repo}

subscriptions_url string<uri>
required

Example: https://api.github.com/users/octocat/subscriptions

type string
required

Example: User

url string<uri>
required

Example: https://api.github.com/users/octocat

has_multiple_single_files boolean
optional

Example: true

permissions App Permissions object
required

The permissions granted to the user-to-server access token.

Example:
{
  "contents": "read",
  "deployments": "write",
  "issues": "read",
  "single_file": "read"
}
actions string
optional

The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. Can be one of: `read` or `write`.

Allowed: "read""write"

administration string
optional

The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. Can be one of: `read` or `write`.

Allowed: "read""write"

checks string
optional

The level of permission to grant the access token for checks on code. Can be one of: `read` or `write`.

Allowed: "read""write"

content_references string
optional

The level of permission to grant the access token for notification of content references and creation content attachments. Can be one of: `read` or `write`.

Allowed: "read""write"

contents string
optional

The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. Can be one of: `read` or `write`.

Allowed: "read""write"

deployments string
optional

The level of permission to grant the access token for deployments and deployment statuses. Can be one of: `read` or `write`.

Allowed: "read""write"

environments string
optional

The level of permission to grant the access token for managing repository environments. Can be one of: `read` or `write`.

Allowed: "read""write"

issues string
optional

The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. Can be one of: `read` or `write`.

Allowed: "read""write"

members string
optional

The level of permission to grant the access token for organization teams and members. Can be one of: `read` or `write`.

Allowed: "read""write"

metadata string
optional

The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_administration string
optional

The level of permission to grant the access token to manage access to an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_hooks string
optional

The level of permission to grant the access token to manage the post-receive hooks for an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_packages string
optional

The level of permission to grant the access token for organization packages published to GitHub Packages. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_plan string
optional

The level of permission to grant the access token for viewing an organization's plan. Can be one of: `read`.

Allowed: "read"

organization_projects string
optional

The level of permission to grant the access token to manage organization projects and projects beta (where available). Can be one of: `read`, `write`, or `admin`.

Allowed: "read""write""admin"

organization_secrets string
optional

The level of permission to grant the access token to manage organization secrets. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_self_hosted_runners string
optional

The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_user_blocking string
optional

The level of permission to grant the access token to view and manage users blocked by the organization. Can be one of: `read` or `write`.

Allowed: "read""write"

packages string
optional

The level of permission to grant the access token for packages published to GitHub Packages. Can be one of: `read` or `write`.

Allowed: "read""write"

pages string
optional

The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. Can be one of: `read` or `write`.

Allowed: "read""write"

pull_requests string
optional

The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. Can be one of: `read` or `write`.

Allowed: "read""write"

repository_hooks string
optional

The level of permission to grant the access token to manage the post-receive hooks for a repository. Can be one of: `read` or `write`.

Allowed: "read""write"

repository_projects string
optional

The level of permission to grant the access token to manage repository projects, columns, and cards. Can be one of: `read`, `write`, or `admin`.

Allowed: "read""write""admin"

secret_scanning_alerts string
optional

The level of permission to grant the access token to view and manage secret scanning alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

secrets string
optional

The level of permission to grant the access token to manage repository secrets. Can be one of: `read` or `write`.

Allowed: "read""write"

security_events string
optional

The level of permission to grant the access token to view and manage security events like code scanning alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

single_file string
optional

The level of permission to grant the access token to manage just a single file. Can be one of: `read` or `write`.

Allowed: "read""write"

statuses string
optional

The level of permission to grant the access token for commit statuses. Can be one of: `read` or `write`.

Allowed: "read""write"

team_discussions string
optional

The level of permission to grant the access token to manage team discussions and related comments. Can be one of: `read` or `write`.

Allowed: "read""write"

vulnerability_alerts string
optional

The level of permission to grant the access token to manage Dependabot alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

workflows string
optional

The level of permission to grant the access token to update GitHub Actions workflow files. Can be one of: `write`.

Allowed: "write"

repositories_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

repository_selection string
required

Describe whether all repositories have been selected or there's a selection involved

Allowed: "all""selected"

single_file_name string
requirednullable

Example: config.yaml

single_file_paths array[string]
optional
Example:
[
  "config.yml",
  ".github/issue_TEMPLATE.md"
]
note string
requirednullable
note_url string<uri>
requirednullable
scopes array[string]
requirednullable

A list of scopes that this authorization is in.

token string
required
token_last_eight string
requirednullable
updated_at string<date-time>
required
url string<uri>
required
user Simple User object
optionalnullable

Simple User

avatar_url string<uri>
required

Example: https://github.com/images/error/octocat_happy.gif

email string
optionalnullable
events_url string
required

Example: https://api.github.com/users/octocat/events{/privacy}

followers_url string<uri>
required

Example: https://api.github.com/users/octocat/followers

following_url string
required

Example: https://api.github.com/users/octocat/following{/other_user}

gists_url string
required

Example: https://api.github.com/users/octocat/gists{/gist_id}

gravatar_id string
requirednullable

Example: 41d064eb2195891e12d0413f63227ea7

html_url string<uri>
required

Example: https://github.com/octocat

id integer
required

Example: 1

login string
required

Example: octocat

name string
optionalnullable
node_id string
required

Example: MDQ6VXNlcjE=

organizations_url string<uri>
required

Example: https://api.github.com/users/octocat/orgs

received_events_url string<uri>
required

Example: https://api.github.com/users/octocat/received_events

repos_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

site_admin boolean
required
starred_at string
optional

Example: "2020-07-09T00:17:55Z"

starred_url string
required

Example: https://api.github.com/users/octocat/starred{/owner}{/repo}

subscriptions_url string<uri>
required

Example: https://api.github.com/users/octocat/subscriptions

type string
required

Example: User

url string<uri>
required

Example: https://api.github.com/users/octocat

application/json Authorization object

**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/[email protected]/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/[email protected]/rest/reference/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).

Headers
Location string

Example: https://api.github.com/authorizations/1

app object
required
client_id string
required
name string
required
url string<uri>
required
created_at string<date-time>
required
fingerprint string
requirednullable
hashed_token string
requirednullable
id integer
required
installation Scoped Installation object
optionalnullable
account Simple User object
required

Simple User

avatar_url string<uri>
required

Example: https://github.com/images/error/octocat_happy.gif

email string
optionalnullable
events_url string
required

Example: https://api.github.com/users/octocat/events{/privacy}

followers_url string<uri>
required

Example: https://api.github.com/users/octocat/followers

following_url string
required

Example: https://api.github.com/users/octocat/following{/other_user}

gists_url string
required

Example: https://api.github.com/users/octocat/gists{/gist_id}

gravatar_id string
requirednullable

Example: 41d064eb2195891e12d0413f63227ea7

html_url string<uri>
required

Example: https://github.com/octocat

id integer
required

Example: 1

login string
required

Example: octocat

name string
optionalnullable
node_id string
required

Example: MDQ6VXNlcjE=

organizations_url string<uri>
required

Example: https://api.github.com/users/octocat/orgs

received_events_url string<uri>
required

Example: https://api.github.com/users/octocat/received_events

repos_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

site_admin boolean
required
starred_at string
optional

Example: "2020-07-09T00:17:55Z"

starred_url string
required

Example: https://api.github.com/users/octocat/starred{/owner}{/repo}

subscriptions_url string<uri>
required

Example: https://api.github.com/users/octocat/subscriptions

type string
required

Example: User

url string<uri>
required

Example: https://api.github.com/users/octocat

has_multiple_single_files boolean
optional

Example: true

permissions App Permissions object
required

The permissions granted to the user-to-server access token.

Example:
{
  "contents": "read",
  "deployments": "write",
  "issues": "read",
  "single_file": "read"
}
actions string
optional

The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts. Can be one of: `read` or `write`.

Allowed: "read""write"

administration string
optional

The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation. Can be one of: `read` or `write`.

Allowed: "read""write"

checks string
optional

The level of permission to grant the access token for checks on code. Can be one of: `read` or `write`.

Allowed: "read""write"

content_references string
optional

The level of permission to grant the access token for notification of content references and creation content attachments. Can be one of: `read` or `write`.

Allowed: "read""write"

contents string
optional

The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges. Can be one of: `read` or `write`.

Allowed: "read""write"

deployments string
optional

The level of permission to grant the access token for deployments and deployment statuses. Can be one of: `read` or `write`.

Allowed: "read""write"

environments string
optional

The level of permission to grant the access token for managing repository environments. Can be one of: `read` or `write`.

Allowed: "read""write"

issues string
optional

The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones. Can be one of: `read` or `write`.

Allowed: "read""write"

members string
optional

The level of permission to grant the access token for organization teams and members. Can be one of: `read` or `write`.

Allowed: "read""write"

metadata string
optional

The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_administration string
optional

The level of permission to grant the access token to manage access to an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_hooks string
optional

The level of permission to grant the access token to manage the post-receive hooks for an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_packages string
optional

The level of permission to grant the access token for organization packages published to GitHub Packages. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_plan string
optional

The level of permission to grant the access token for viewing an organization's plan. Can be one of: `read`.

Allowed: "read"

organization_projects string
optional

The level of permission to grant the access token to manage organization projects and projects beta (where available). Can be one of: `read`, `write`, or `admin`.

Allowed: "read""write""admin"

organization_secrets string
optional

The level of permission to grant the access token to manage organization secrets. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_self_hosted_runners string
optional

The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization. Can be one of: `read` or `write`.

Allowed: "read""write"

organization_user_blocking string
optional

The level of permission to grant the access token to view and manage users blocked by the organization. Can be one of: `read` or `write`.

Allowed: "read""write"

packages string
optional

The level of permission to grant the access token for packages published to GitHub Packages. Can be one of: `read` or `write`.

Allowed: "read""write"

pages string
optional

The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds. Can be one of: `read` or `write`.

Allowed: "read""write"

pull_requests string
optional

The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges. Can be one of: `read` or `write`.

Allowed: "read""write"

repository_hooks string
optional

The level of permission to grant the access token to manage the post-receive hooks for a repository. Can be one of: `read` or `write`.

Allowed: "read""write"

repository_projects string
optional

The level of permission to grant the access token to manage repository projects, columns, and cards. Can be one of: `read`, `write`, or `admin`.

Allowed: "read""write""admin"

secret_scanning_alerts string
optional

The level of permission to grant the access token to view and manage secret scanning alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

secrets string
optional

The level of permission to grant the access token to manage repository secrets. Can be one of: `read` or `write`.

Allowed: "read""write"

security_events string
optional

The level of permission to grant the access token to view and manage security events like code scanning alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

single_file string
optional

The level of permission to grant the access token to manage just a single file. Can be one of: `read` or `write`.

Allowed: "read""write"

statuses string
optional

The level of permission to grant the access token for commit statuses. Can be one of: `read` or `write`.

Allowed: "read""write"

team_discussions string
optional

The level of permission to grant the access token to manage team discussions and related comments. Can be one of: `read` or `write`.

Allowed: "read""write"

vulnerability_alerts string
optional

The level of permission to grant the access token to manage Dependabot alerts. Can be one of: `read` or `write`.

Allowed: "read""write"

workflows string
optional

The level of permission to grant the access token to update GitHub Actions workflow files. Can be one of: `write`.

Allowed: "write"

repositories_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

repository_selection string
required

Describe whether all repositories have been selected or there's a selection involved

Allowed: "all""selected"

single_file_name string
requirednullable

Example: config.yaml

single_file_paths array[string]
optional
Example:
[
  "config.yml",
  ".github/issue_TEMPLATE.md"
]
note string
requirednullable
note_url string<uri>
requirednullable
scopes array[string]
requirednullable

A list of scopes that this authorization is in.

token string
required
token_last_eight string
requirednullable
updated_at string<date-time>
required
url string<uri>
required
user Simple User object
optionalnullable

Simple User

avatar_url string<uri>
required

Example: https://github.com/images/error/octocat_happy.gif

email string
optionalnullable
events_url string
required

Example: https://api.github.com/users/octocat/events{/privacy}

followers_url string<uri>
required

Example: https://api.github.com/users/octocat/followers

following_url string
required

Example: https://api.github.com/users/octocat/following{/other_user}

gists_url string
required

Example: https://api.github.com/users/octocat/gists{/gist_id}

gravatar_id string
requirednullable

Example: 41d064eb2195891e12d0413f63227ea7

html_url string<uri>
required

Example: https://github.com/octocat

id integer
required

Example: 1

login string
required

Example: octocat

name string
optionalnullable
node_id string
required

Example: MDQ6VXNlcjE=

organizations_url string<uri>
required

Example: https://api.github.com/users/octocat/orgs

received_events_url string<uri>
required

Example: https://api.github.com/users/octocat/received_events

repos_url string<uri>
required

Example: https://api.github.com/users/octocat/repos

site_admin boolean
required
starred_at string
optional

Example: "2020-07-09T00:17:55Z"

starred_url string
required

Example: https://api.github.com/users/octocat/starred{/owner}{/repo}

subscriptions_url string<uri>
required

Example: https://api.github.com/users/octocat/subscriptions

type string
required

Example: User

url string<uri>
required

Example: https://api.github.com/users/octocat

Not modified

application/json Basic Error object

Requires authentication

documentation_url string
optional
message string
optional
status string
optional
url string
optional
application/json Basic Error object

Forbidden

documentation_url string
optional
message string
optional
status string
optional
url string
optional
application/json Validation Error object

Validation failed

documentation_url string
required
errors array[object]
optional
items object
code string
required
field string
optional
index integer
optional
message string
optional
resource string
optional
value
optional
message string
required