v50

latestOpenAPI 3.0.3MITraw.githubusercontent.com2023-11-288093493.9 MB

oauth-authorizations

Get-or-create an authorization for a specific app

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, 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. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

Warning: Apps must use the 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.

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}

Path parameters

client_idstring required

The client ID of the OAuth app.

Request body

client_secretstring required

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

scopesstring[] nullable

A list of scopes that this authorization is in.

notestring

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

note_urlstring

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

fingerprintstring

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

Example request

{
  "scopes": [
    "public_repo",
    "user"
  ],
  "note": "Update all gems"
}

Response

if returning an existing token

idinteger required

urlstring uri required

scopesstring[] nullable required

A list of scopes that this authorization is in.

tokenstring required

token_last_eightstring nullable required

hashed_tokenstring nullable required

notestring nullable required

note_urlstring uri nullable required

updated_atstring date-time required

created_atstring date-time required

fingerprintstring nullable required

expires_atstring date-time nullable required

Example response

{
  "user": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "41d064eb2195891e12d0413f63227ea7",
    "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",
    "starred_at": "\"2020-07-09T00:17:55Z\""
  },
  "installation": {
    "permissions": {
      "contents": "read",
      "issues": "read",
      "deployments": "write",
      "single_file": "read"
    },
    "single_file_name": "config.yaml",
    "has_multiple_single_files": true,
    "single_file_paths": [
      "config.yml",
      ".github/issue_TEMPLATE.md"
    ],
    "repositories_url": "https://api.github.com/users/octocat/repos",
    "account": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "41d064eb2195891e12d0413f63227ea7",
      "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",
      "starred_at": "\"2020-07-09T00:17:55Z\""
    }
  }
}