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

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). 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](https://docs.github.com/[email protected]/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."

PUT/authorizations/clients/{client_id}/{fingerprint}

Source: github-v3-rest.json
Revision: f5f067c1e6f6
Active snapshot: 85e53e3d0d65

Request

Path Parameters

client_id string required: The client ID of your GitHub app.
fingerprint string required

Body Params

required

application/jsonobject

client_secret string

required

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

maxLength:40

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

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

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

Response Example: 200 application/json

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

application/json Authorization object

Response if returning a new 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

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

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

Response Example: 201 application/json

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

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

Request configuration

This OpenAPI document does not declare an authentication scheme. Check the API provider's documentation before sending credentials; Manja cannot infer or validate an undocumented scheme.

Common bearer example: Authorization: Bearer YOUR_ACCESS_TOKEN

hostname

Self-hosted Enterprise Server or Enterprise Cloud hostname

protocol

Self-hosted Enterprise Server or Enterprise Cloud protocol

client_id *

The client ID of your GitHub app.

fingerprint *

Request Sample: Shell / cURL

curl --request PUT \
  --url {protocol}://{hostname}/api/v3/authorizations/clients/{client_id}/{fingerprint} \
  --header 'content-type: application/json' \
  --data '{
  "client_secret": "string",
  "note": "string",
  "note_url": "string",
  "scopes": [
    "string"
  ]
}'