# Create a new authorization

From **GitHub v3 REST API**.

`POST /authorizations`

**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 OAuth tokens using [Basic Authentication](https://docs.github.com/enterprise-server@3.0/rest/overview/other-authentication-methods#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](https://docs.github.com/enterprise-server@3.0/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."

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 Enterprise Server from the [personal access tokens settings](https://github.com/settings/tokens) page. Read more about these tokens in [the GitHub Help documentation](https://docs.github.com/articles/creating-an-access-token-for-command-line-use).

Organizations that enforce SAML SSO require personal access tokens to be allowed. Read more about allowing tokens in [the GitHub Help documentation](https://docs.github.com/articles/about-identity-and-access-management-with-saml-single-sign-on).

## Request body

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

- Type: `object`

```json
{"properties":{"client_id":{"description":"The OAuth app client key for which to create the token.","maxLength":20,"type":"string"},"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"}},"type":"object"}
```

## Responses

### `201`

Response

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

### `410`

Gone

### `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 POST \
  --url {protocol}://{hostname}/api/v3/authorizations \
  --header 'content-type: application/json' \
  --data '{
  "client_id": "string",
  "client_secret": "string",
  "fingerprint": "string",
  "note": "string",
  "note_url": "string",
  "scopes": [
    "string"
  ]
}'
```