Github how to create token

Authorizing OAuth Apps

In this article

You can enable other users to authorize your OAuth App.

GitHub’s OAuth implementation supports the standard authorization code grant type and the OAuth 2.0 Device Authorization Grant for apps that don’t have access to a web browser.

If you want to skip authorizing your app in the standard way, such as when testing your app, you can use the non-web application flow.

To authorize your OAuth app, consider which authorization flow best fits your app.

Web application flow

Note: If you are building a GitHub App, you can still use the OAuth web application flow, but the setup has some important differences. See «Identifying and authorizing users for GitHub Apps» for more information.

The web application flow to authorize users for your app is:

1. Request a user’s GitHub identity

When your GitHub App specifies a login parameter, it prompts users with a specific account they can use for signing in and authorizing your app.

2. Users are redirected back to your site by GitHub

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. The temporary code will expire after 10 minutes. If the states don’t match, then a third party created the request, and you should abort the process.

Exchange this code for an access token:

By default, the response takes the following form:

You can also receive the response in different formats if you provide the format in the Accept header. For example, Accept: application/json or Accept: application/xml :

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

For example, in curl you can set the Authorization header like this:

Note: The device flow is in public beta and subject to change.

The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.

Before you can use the device flow to authorize and identify users, you must first enable it in your app’s settings. For more information about enabling the device flow in your app, see «Modifying an OAuth App» for OAuth Apps and «Modifying a GitHub App» for GitHub Apps.

Overview of the device flow

Step 1: App requests the device and user verification codes from GitHub

Your app must request a user verification code and verification URL that the app will use to prompt the user to authenticate in the next step. This request also returns a device verification code that the app must use to receive an access token and check the status of user authentication.

By default, the response takes the following form:

You can also receive the response in different formats if you provide the format in the Accept header. For example, Accept: application/json or Accept: application/xml :

Step 2: Prompt the user to enter the user code in a browser

Step 3: App polls GitHub to check if the user authorized the device

Once the user has authorized, the app will receive an access token that can be used to make requests to the API on behalf of a user.

By default, the response takes the following form:

You can also receive the response in different formats if you provide the format in the Accept header. For example, Accept: application/json or Accept: application/xml :

Rate limits for the device flow

When a user submits the verification code on the browser, there is a rate limit of 50 submissions in an hour per application.

Error codes for the device flow

Non-Web application flow

Non-web authentication is available for limited situations like testing. If you need to, you can use Basic Authentication to create a personal access token using your Personal access tokens settings page. This technique enables the user to revoke access at any time.

Note: When using the non-web application flow to create an OAuth2 token, make sure to understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.

The redirect_uri parameter is optional. If left out, GitHub will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.

Localhost redirect urls

The optional redirect_uri parameter can also be used for localhost URLs. If the application specifies a localhost URL and a port, then after authorizing the application users will be redirected to the provided URL and port. The redirect_uri does not need to match the port specified in the callback url for the app.

For the http://127.0.0.1/path callback URL, you can use this redirect_uri :

Creating multiple tokens for OAuth Apps

You can create multiple tokens for a user/application/scope combination to create tokens for specific use cases.

This is useful if your OAuth App supports one workflow that uses GitHub for sign-in and only requires basic user information. Another workflow may require access to a user’s private repositories. Using multiple tokens, your OAuth App can perform the web flow for each use case, requesting only the scopes needed. If a user only uses your application to sign in, they are never required to grant your OAuth App access to their private repositories.

There is a limit of ten tokens that are issued per user/application/scope combination. If an application creates more than 10 tokens for the same user and the same scopes, the oldest tokens with the same user/application/scope combination will be revoked.

Warning: Revoking all permission from an OAuth App deletes any SSH keys the application generated on behalf of the user, including deploy keys.

Directing users to review their access

You can link to authorization information for an OAuth App so that users can review and revoke their application authorizations.

To build this link, you’ll need your OAuth Apps client_id that you received from GitHub when you registered the application.

Tip: To learn more about the resources that your OAuth App can access for a user, see «Discovering resources for a user.»

About authentication to GitHub

In this article

You can securely access your account’s resources by authenticating to GitHub, using different credentials depending on where you authenticate.

About authentication to GitHub

To keep your account secure, you must authenticate before you can access certain resources on GitHub. When you authenticate to GitHub, you supply or confirm credentials that are unique to you to prove that you are exactly who you declare to be.

You can access your resources in GitHub in a variety of ways: in the browser, via GitHub Desktop or another desktop application, with the API, or via the command line. Each way of accessing GitHub supports different modes of authentication.

Authenticating in your browser

If you’re a member of an enterprise with managed users, you will authenticate to GitHub in your browser using your IdP. For more information, see «Authenticating as a managed user» in the GitHub Enterprise Cloud documentation.

If you’re not a member of an enterprise with managed users, you will authenticate using your GitHub.com username and password. You may also use two-factor authentication and SAML single sign-on, which can be required by organization and enterprise owners.

Username and password only

You’ll create a password when you create your account on GitHub. We recommend that you use a password manager to generate a random and unique password. For more information, see «Creating a strong password.»

If you have not enabled 2FA, GitHub will ask for additional verification when you first sign in from an unrecognized device, such as a new browser profile, a browser where the cookies have been deleted, or a new computer.

After providing your username and password, you will be asked to provide a verification code that we will send to you via email. If you have the GitHub Mobile application installed, you’ll receive a notification there instead. For more information, see «GitHub Mobile.»

Two-factor authentication (2FA) (recommended)

SAML single sign-on

Authenticating with GitHub Desktop

You can authenticate with GitHub Desktop using your browser. For more information, see «Authenticating to GitHub.»

Authenticating with the API

You can authenticate with the API in different ways.

Authenticating with the command line

You can access repositories on GitHub from the command line in two ways, HTTPS and SSH, and both have a different way of authenticating. The method of authenticating is determined based on whether you choose an HTTPS or SSH remote URL when you clone the repository. For more information about which way to access, see «About remote repositories.»

You can work with all repositories on GitHub over HTTPS, even if you are behind a firewall or proxy.

If you authenticate without GitHub CLI, you must authenticate with a personal access token. When Git prompts you for your password, enter your personal access token (PAT). Alternatively, you can use a credential helper like Git Credential Manager. Password-based authentication for Git has been removed in favor of more secure authentication methods. For more information, see «Creating a personal access token.» Every time you use Git to authenticate with GitHub, you’ll be prompted to enter your credentials to authenticate with GitHub, unless you cache them with a credential helper.

You can work with all repositories on GitHub over SSH, although firewalls and proxies might refuse to allow SSH connections.

If you authenticate without GitHub CLI, you will need to generate an SSH public/private keypair on your local machine and add the public key to your account on GitHub.com. For more information, see «Generating a new SSH key and adding it to the ssh-agent.» Every time you use Git to authenticate with GitHub, you’ll be prompted to enter your SSH key passphrase, unless you’ve stored the key.

Authorizing for SAML single sign-on

To use a personal access token or SSH key to access resources owned by an organization that uses SAML single sign-on, you must also authorize the personal token or SSH key. For more information, see «Authorizing a personal access token for use with SAML single sign-on» or «Authorizing an SSH key for use with SAML single sign-on» in the GitHub Enterprise Cloud documentation.

GitHub’s token formats

GitHub issues tokens that begin with a prefix to indicate the token’s type.

Help us make these docs great!

All GitHub docs are open source. See something that’s wrong or unclear? Submit a pull request.

Automatic token authentication

In this article

GitHub provides a token that you can use to authenticate on behalf of GitHub Actions.

About the GITHUB_TOKEN secret

At the start of each workflow run, GitHub automatically creates a unique GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run.

Before each job begins, GitHub fetches an installation access token for the job. The GITHUB_TOKEN expires when a job finishes or after a maximum of 24 hours.

The token is also available in the github.token context. For more information, see «Contexts.»

Using the GITHUB_TOKEN in a workflow

Example 1: passing the GITHUB_TOKEN as an input

This example workflow uses the labeler action, which requires the GITHUB_TOKEN as the value for the repo-token input parameter:

Example 2: calling the REST API

You can use the GITHUB_TOKEN to make authenticated API calls. This example workflow creates an issue using the GitHub REST API:

Permissions for the GITHUB_TOKEN

For information about the API endpoints GitHub Apps can access with each permission, see «GitHub App Permissions.»

The following table shows the permissions granted to the GITHUB_TOKEN by default. People with admin permissions to an enterprise, organization, or repository, can set the default permissions to be either permissive or restricted. For information on how to set the default permissions for the GITHUB_TOKEN for your enterprise, organization, or repository, see «Enforcing policies for GitHub Actions in your enterprise,» «Disabling or limiting GitHub Actions for your organization,» or «Managing GitHub Actions settings for a repository.»

Modifying the permissions for the GITHUB_TOKEN

You can see the permissions that GITHUB_TOKEN had for a specific job in the «Set up job» section of the workflow run log. For more information, see «Using workflow run logs.»

You can use the permissions key in your workflow file to modify permissions for the GITHUB_TOKEN for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job. When the permissions key is used, all unspecified permissions are set to no access, with the exception of the metadata scope, which always gets read access.

You can use the permissions key to add and remove read permissions for forked repositories, but typically you can’t grant write access. The exception to this behavior is where an admin user has selected the Send write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, see «Managing GitHub Actions settings for a repository.»

The two workflow examples earlier in this article show the permissions key being used at the workflow level, and at the job level. In Example 1 the two permissions are specified for the entire workflow. In Example 2 write access is granted for one scope for a single job.

For full details of the permissions key, see «Workflow syntax for GitHub Actions.»

How the permissions are calculated for a workflow job

The permissions for the GITHUB_TOKEN are initially set to the default setting for the enterprise, organization, or repository. If the default is set to the restricted permissions at any of these levels then this will apply to the relevant repositories. For example, if you choose the restricted default at the organization level then all repositories in that organization will use the restricted permissions as the default. The permissions are then adjusted based on any configuration within the workflow file, first at the workflow level and then at the job level. Finally, if the workflow was triggered by a pull request from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only.

Granting additional permissions

Other authentication methods

In this article

You can use basic authentication for testing in a non-production environment.

While the API provides multiple methods for authentication, we strongly recommend using OAuth for production applications. The other methods provided are intended to be used for scripts or testing (i.e., cases where full OAuth would be overkill). Third party applications that rely on GitHub for authentication should not ask for or collect GitHub credentials. Instead, they should use the OAuth web flow.

Via OAuth and personal access tokens

We recommend you use OAuth tokens to authenticate to the GitHub API. OAuth tokens include personal access tokens and enable the user to revoke access at any time.

This approach is useful if your tools only support Basic Authentication but you want to take advantage of OAuth access token security features.

Via username and password

Note: GitHub has discontinued password authentication to the API starting on November 13, 2020 for all GitHub.com accounts, including those on a GitHub Free, GitHub Pro, GitHub Team, or GitHub Enterprise Cloud plan. You must now authenticate to the GitHub API with an API token, such as an OAuth access token, GitHub App installation access token, or personal access token, depending on what you need to do with the token. For more information, see «Troubleshooting.»

Authenticating for SAML SSO

Note: Integrations and OAuth applications that generate tokens on behalf of others are automatically authorized.

If you’re using the API to access an organization that enforces SAML SSO for authentication, you’ll need to create a personal access token (PAT) and authorize the token for that organization. Visit the URL specified in X-GitHub-SSO to authorize the token for the organization.

When requesting data that could come from multiple organizations (for example, requesting a list of issues created by the user), the X-GitHub-SSO header indicates which organizations require you to authorize your personal access token:

The value organizations is a comma-separated list of organization IDs for organizations require authorization of your personal access token.

Working with two-factor authentication

When you have two-factor authentication enabled, Basic Authentication for most endpoints in the REST API requires that you use a personal access token.

You can generate a new personal access token using GitHub developer settings. For more information, see «Creating a personal access token for the command line». Then you would use these tokens to authenticate using OAuth token with the GitHub API.

Help us make these docs great!

All GitHub docs are open source. See something that’s wrong or unclear? Submit a pull request.

Authenticating with GitHub Apps

In this article

You can authenticate as a GitHub App or as an installation.

Generating a private key

After you create a GitHub App, you’ll need to generate one or more private keys. You’ll use the private key to sign access token requests.

You can create multiple private keys and rotate them to prevent downtime if a key is compromised or lost. To verify that a private key matches a public key, see Verifying private keys.

To generate a private key:

In the upper-right corner of any page, click your profile photo, then click Settings.

In the left sidebar, click

In the left sidebar, click GitHub Apps.

To the right of the GitHub App you want to modify, click Edit.

In «Private keys», click Generate a private key.

You will see a private key in PEM format downloaded to your computer. Make sure to store this file because GitHub only stores the public portion of the key.

Note: If you’re using a library that requires a specific file format, the PEM file you download will be in PKCS#1 RSAPrivateKey format.

Verifying private keys

GitHub generates a fingerprint for each private and public key pair using the SHA-256 hash function. You can verify that your private key matches the public key stored on GitHub by generating the fingerprint of your private key and comparing it to the fingerprint shown on GitHub.

To verify a private key:

Deleting private keys

You can remove a lost or compromised private key by deleting it, but you must have at least one private key. When you only have one key, you will need to generate a new one before deleting the old one.

Authenticating as a GitHub App

Authenticating as a GitHub App lets you do a couple of things:

To authenticate as a GitHub App, generate a private key in PEM format and download it to your local machine. You’ll use this key to sign a JSON Web Token (JWT) and encode it using the RS256 algorithm. GitHub checks that the request is authenticated by verifying the token with the app’s stored public key.

Here’s a quick Ruby script you can use to generate a JWT. Note you’ll have to run gem install jwt before using it.

YOUR_PATH_TO_PEM and YOUR_APP_ID are the values you must replace. Make sure to enclose the values in double quotes.

Use your GitHub App’s identifier ( YOUR_APP_ID ) as the value for the JWT iss (issuer) claim. You can obtain the GitHub App identifier via the initial webhook ping after creating the app, or at any time from the app settings page in the GitHub.com UI.

After creating the JWT, set it in the Header of the API request:

YOUR_JWT is the value you must replace.

The example above uses the maximum expiration time of 10 minutes, after which the API will start returning a 401 error:

You’ll need to create a new JWT after the time expires.

Accessing API endpoints as a GitHub App

For a list of REST API endpoints you can use to get high-level information about a GitHub App, see «GitHub Apps.»

Authenticating as an installation

Authenticating as an installation lets you perform actions in the API for that installation. Before authenticating as an installation, you must create an installation access token. Ensure that you have already installed your GitHub App to at least one repository; it is impossible to create an installation token without a single installation. These installation access tokens are used by GitHub Apps to authenticate. For more information, see «Installing GitHub Apps.»

By default, installation access tokens are scoped to all the repositories that an installation can access. You can limit the scope of the installation access token to specific repositories by using the repository_ids parameter. See the Create an installation access token for an app endpoint for more details. Installation access tokens have the permissions configured by the GitHub App and expire after one hour.

To list the installations for an authenticated app, include the JWT generated above in the Authorization header in the API request:

The response will include a list of installations where each installation’s id can be used for creating an installation access token. For more information about the response format, see «List installations for the authenticated app.»

To create an installation access token, include the JWT generated above in the Authorization header in the API request and replace :installation_id with the installation’s id :

The response will include your installation access token, the expiration date, the token’s permissions, and the repositories that the token can access. For more information about the response format, see the Create an installation access token for an app endpoint.

To authenticate with an installation access token, include it in the Authorization header in the API request:

YOUR_INSTALLATION_ACCESS_TOKEN is the value you must replace.

Accessing API endpoints as an installation

For a list of REST API endpoints that are available for use by GitHub Apps using an installation access token, see «Available Endpoints.»

For a list of endpoints related to installations, see «Installations.»

HTTP-based Git access by an installation

Installations with permissions on contents of a repository, can use their installation access tokens to authenticate for Git access. Use the installation access token as the HTTP password:

Help us make these docs great!

All GitHub docs are open source. See something that’s wrong or unclear? Submit a pull request.