---
title: "Get-or-create an authorization for a specific app"
method: PUT
path: "/authorizations/clients/{client_id}"
tags: ["oauth-authorizations"]
deprecated: true
---

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

`PUT /authorizations/clients/{client_id}`

> **Deprecated.**

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

## Path parameters

- `client_id` string, required

## Request body

- object
  - `client_secret` string, required — The OAuth app client secret for which to create the token.
  - `scopes` string[], nullable — A list of scopes that this authorization is in.
  - `note` string — A note to remind you what the OAuth token is for.
  - `note_url` string — A URL to remind you what app the OAuth token is for.
  - `fingerprint` string — A unique string to distinguish an authorization from others created for the same client ID and user.

## Response `200`

if returning an existing token

- Authorization — The authorization for an OAuth app, GitHub App, or a Personal Access Token.
  - `id` integer, required
  - `url` string, uri, required
  - `scopes` string[], nullable, required — A list of scopes that this authorization is in.
  - `token` string, required
  - `token_last_eight` string, nullable, required
  - `hashed_token` string, nullable, required
  - `app` object, required
    - `client_id` string, required
    - `name` string, required
    - `url` string, uri, required
  - `note` string, nullable, required
  - `note_url` string, uri, nullable, required
  - `updated_at` string, date-time, required
  - `created_at` string, date-time, required
  - `fingerprint` string, nullable, required
  - `user` NullableSimpleUser, nullable — A GitHub user.
    - `name` string, nullable
    - `email` string, nullable
    - `login` string, required
    - `id` integer, required
    - `node_id` string, required
    - `avatar_url` string, uri, required
    - `gravatar_id` string, nullable, required
    - `url` string, uri, required
    - `html_url` string, uri, required
    - `followers_url` string, uri, required
    - `following_url` string, required
    - `gists_url` string, required
    - `starred_url` string, required
    - `subscriptions_url` string, uri, required
    - `organizations_url` string, uri, required
    - `repos_url` string, uri, required
    - `events_url` string, required
    - `received_events_url` string, uri, required
    - `type` string, required
    - `site_admin` boolean, required
    - `starred_at` string
  - `installation` NullableScopedInstallation, nullable
    - `permissions` AppPermissions, required — The permissions granted to the user access token.
      - `actions` 'read' | 'write' — The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts.
      - `administration` 'read' | 'write' — The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation.
      - `checks` 'read' | 'write' — The level of permission to grant the access token for checks on code.
      - `codespaces` 'read' | 'write' — The level of permission to grant the access token to create, edit, delete, and list Codespaces.
      - `contents` 'read' | 'write' — The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.
      - `dependabot_secrets` 'read' | 'write' — The leve of permission to grant the access token to manage Dependabot secrets.
      - `deployments` 'read' | 'write' — The level of permission to grant the access token for deployments and deployment statuses.
      - `environments` 'read' | 'write' — The level of permission to grant the access token for managing repository environments.
      - `issues` 'read' | 'write' — The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones.
      - `metadata` 'read' | 'write' — The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata.
      - `packages` 'read' | 'write' — The level of permission to grant the access token for packages published to GitHub Packages.
      - `pages` 'read' | 'write' — The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds.
      - `pull_requests` 'read' | 'write' — The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges.
      - `repository_hooks` 'read' | 'write' — The level of permission to grant the access token to manage the post-receive hooks for a repository.
      - `repository_projects` 'read' | 'write' | 'admin' — The level of permission to grant the access token to manage repository projects, columns, and cards.
      - `secret_scanning_alerts` 'read' | 'write' — The level of permission to grant the access token to view and manage secret scanning alerts.
      - `secrets` 'read' | 'write' — The level of permission to grant the access token to manage repository secrets.
      - `security_events` 'read' | 'write' — The level of permission to grant the access token to view and manage security events like code scanning alerts.
      - `single_file` 'read' | 'write' — The level of permission to grant the access token to manage just a single file.
      - `statuses` 'read' | 'write' — The level of permission to grant the access token for commit statuses.
      - `vulnerability_alerts` 'read' | 'write' — The level of permission to grant the access token to manage Dependabot alerts.
      - `workflows` 'write' — The level of permission to grant the access token to update GitHub Actions workflow files.
      - `members` 'read' | 'write' — The level of permission to grant the access token for organization teams and members.
      - `organization_administration` 'read' | 'write' — The level of permission to grant the access token to manage access to an organization.
      - `organization_copilot_seat_management` 'write' — The level of permission to grant the access token for managing access to GitHub Copilot for members of an organization with a Copilot Business subscription. This property is in beta and is subject to change.
      - `organization_announcement_banners` 'read' | 'write' — The level of permission to grant the access token to view and manage announcement banners for an organization.
      - `organization_events` 'read' — The level of permission to grant the access token to view events triggered by an activity in an organization.
      - `organization_hooks` 'read' | 'write' — The level of permission to grant the access token to manage the post-receive hooks for an organization.
      - `organization_personal_access_tokens` 'read' | 'write' — The level of permission to grant the access token for viewing and managing fine-grained personal access token requests to an organization.
      - `organization_personal_access_token_requests` 'read' | 'write' — The level of permission to grant the access token for viewing and managing fine-grained personal access tokens that have been approved by an organization.
      - `organization_plan` 'read' — The level of permission to grant the access token for viewing an organization's plan.
      - `organization_projects` 'read' | 'write' | 'admin' — The level of permission to grant the access token to manage organization projects and projects beta (where available).
      - `organization_packages` 'read' | 'write' — The level of permission to grant the access token for organization packages published to GitHub Packages.
      - `organization_secrets` 'read' | 'write' — The level of permission to grant the access token to manage organization secrets.
      - `organization_self_hosted_runners` 'read' | 'write' — The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization.
      - `organization_user_blocking` 'read' | 'write' — The level of permission to grant the access token to view and manage users blocked by the organization.
      - `team_discussions` 'read' | 'write' — The level of permission to grant the access token to manage team discussions and related comments.
      - `email_addresses` 'read' | 'write' — The level of permission to grant the access token to manage the email addresses belonging to a user.
      - `followers` 'read' | 'write' — The level of permission to grant the access token to manage the followers belonging to a user.
      - `git_ssh_keys` 'read' | 'write' — The level of permission to grant the access token to manage git SSH keys.
      - `gpg_keys` 'read' | 'write' — The level of permission to grant the access token to view and manage GPG keys belonging to a user.
      - `interaction_limits` 'read' | 'write' — The level of permission to grant the access token to view and manage interaction limits on a repository.
      - `profile` 'write' — The level of permission to grant the access token to manage the profile settings belonging to a user.
      - `starring` 'read' | 'write' — The level of permission to grant the access token to list and manage repositories a user is starring.
    - `repository_selection` 'all' | 'selected', required — Describe whether all repositories have been selected or there's a selection involved
    - `single_file_name` string, nullable, required
    - `has_multiple_single_files` boolean
    - `single_file_paths` string[]
    - `repositories_url` string, uri, required
    - `account` SimpleUser, required — A GitHub user.
      - `name` string, nullable
      - `email` string, nullable
      - `login` string, required
      - `id` integer, required
      - `node_id` string, required
      - `avatar_url` string, uri, required
      - `gravatar_id` string, nullable, required
      - `url` string, uri, required
      - `html_url` string, uri, required
      - `followers_url` string, uri, required
      - `following_url` string, required
      - `gists_url` string, required
      - `starred_url` string, required
      - `subscriptions_url` string, uri, required
      - `organizations_url` string, uri, required
      - `repos_url` string, uri, required
      - `events_url` string, required
      - `received_events_url` string, uri, required
      - `type` string, required
      - `site_admin` boolean, required
      - `starred_at` string
  - `expires_at` string, date-time, nullable, required

## Other responses

- `201` — **Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.8/rest/oauth-authorizations/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.8/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.8/rest/oauth-authorizations/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/).
- `304` — Not modified
- `401` — Requires authentication
- `403` — Forbidden
- `422` — Validation failed, or the endpoint has been spammed.

---

[API](https://skmtc.net/github/apis/github-v3-rest-api-7.md) · [All operations](https://skmtc.net/github/apis/github-v3-rest-api-7/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/github-v3-rest-api-7/revisions/5438365412fe/schema)