# Get-or-create an authorization for a specific app

From **GitHub v3 REST API**.

`PUT /authorizations/clients/{client_id}`

**Deprecated.**

**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.0/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/enterprise-server@3.0/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.0/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/enterprise-server@3.0/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/enterprise-server@3.0/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/enterprise-server@3.0/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/enterprise-server@3.0/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.0/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/).

## Parameters

### `client_id`

- Location: path
- Required: true
- Type: `string`

The client ID of your GitHub app.

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{"properties":{"client_secret":{"description":"The OAuth app client secret for which to create the token.","maxLength":40,"type":"string"},"fingerprint":{"description":"A unique string to distinguish an authorization from others created for the same client ID and user.","type":"string"},"note":{"description":"A note to remind you what the OAuth token is for.","example":"Update all gems","type":"string"},"note_url":{"description":"A URL to remind you what app the OAuth token is for.","type":"string"},"scopes":{"description":"A list of scopes that this authorization is in.","example":["public_repo","user"],"items":{"type":"string"},"nullable":true,"type":"array"}},"required":["client_secret"],"type":"object"}
```

## Responses

### `200`

if returning an existing token

#### Headers

##### `Location`

- Type: `string`

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

### `application/json`

- Type: `object`

The authorization for an OAuth app, GitHub App, or a Personal Access Token.

```json
{
  "app": {
    "client_id": "abcde12345fghij67890",
    "name": "my github app",
    "url": "http://my-github-app.com"
  },
  "created_at": "2011-09-06T17:26:27Z",
  "fingerprint": "",
  "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"
}
```

```json
{"description":"The authorization for an OAuth app, GitHub App, or a Personal Access Token.","properties":{"app":{"properties":{"client_id":{"type":"string"},"name":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["client_id","name","url"],"type":"object"},"created_at":{"format":"date-time","type":"string"},"fingerprint":{"nullable":true,"type":"string"},"hashed_token":{"nullable":true,"type":"string"},"id":{"type":"integer"},"installation":{"$ref":"#/components/schemas/nullable-scoped-installation"},"note":{"nullable":true,"type":"string"},"note_url":{"format":"uri","nullable":true,"type":"string"},"scopes":{"description":"A list of scopes that this authorization is in.","items":{"type":"string"},"nullable":true,"type":"array"},"token":{"type":"string"},"token_last_eight":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"format":"uri","type":"string"},"user":{"$ref":"#/components/schemas/nullable-simple-user"}},"required":["app","id","note","note_url","scopes","token","hashed_token","token_last_eight","fingerprint","url","created_at","updated_at","expires_at"],"title":"Authorization","type":"object"}
```

### `201`

**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.0/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/enterprise-server@3.0/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.0/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`

- Type: `string`

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

### `application/json`

- Type: `object`

The authorization for an OAuth app, GitHub App, or a Personal Access Token.

```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"
}
```

```json
{"description":"The authorization for an OAuth app, GitHub App, or a Personal Access Token.","properties":{"app":{"properties":{"client_id":{"type":"string"},"name":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["client_id","name","url"],"type":"object"},"created_at":{"format":"date-time","type":"string"},"fingerprint":{"nullable":true,"type":"string"},"hashed_token":{"nullable":true,"type":"string"},"id":{"type":"integer"},"installation":{"$ref":"#/components/schemas/nullable-scoped-installation"},"note":{"nullable":true,"type":"string"},"note_url":{"format":"uri","nullable":true,"type":"string"},"scopes":{"description":"A list of scopes that this authorization is in.","items":{"type":"string"},"nullable":true,"type":"array"},"token":{"type":"string"},"token_last_eight":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"format":"uri","type":"string"},"user":{"$ref":"#/components/schemas/nullable-simple-user"}},"required":["app","id","note","note_url","scopes","token","hashed_token","token_last_eight","fingerprint","url","created_at","updated_at","expires_at"],"title":"Authorization","type":"object"}
```

### `304`

Not modified

### `401`

Requires authentication

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

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