oauth-methods.js

Set of stateless request methods to create, check, reset, refresh, and delete user access tokens for OAuth and GitHub Apps

• Usage
  • OAuth Web Flow
  • OAuth Device Flow
• Methods
  • getWebFlowAuthorizationUrl()
  • exchangeWebFlowCode()
  • createDeviceCode()
  • exchangeDeviceCode()
  • checkToken()
  • refreshToken()
  • scopeToken()
  • resetToken()
  • deleteToken()
  • deleteAuthorization()
• Authentication object
  • OAuth APP authentication
  • GitHub App with non-expiring user authentication
  • GitHub App with expiring user authentication
• Types
• Contributing
• License

The OAuth endpoints related to user access tokens are not all part of GitHub's REST API and they behave slightly different. The methods exported by `@octokit/normalize the differences so you don't have to.

Usage

1import {
2  exchangeWebFlowCode,
3  createDeviceCode,
4  exchangeDeviceCode,
5  checkToken,
6  refreshToken,
7  scopeToken,
8  resetToken,
9  deleteToken,
10  deleteAuthorization,
11} from ("@octokit-next/oauth-methods");

1import {
2  exchangeWebFlowCode,
3  createDeviceCode,
4  exchangeDeviceCode,
5  checkToken,
6  refreshToken,
7  scopeToken,
8  resetToken,
9  deleteToken,
10  deleteAuthorization,
11} from "https://cdn.skypack.dev/@octokit-next/oauth-methods?dts";

OAuth Web Flow

After a user granted access to an OAuth App or GitHub App on Step 1 of GitHub's OAuth Web Flow, they get redirected to a URL controlled by your app with a ?code=... query parameter.

You can exchange that code for a user access token as described in Step 2 of GitHub's OAuth Web Flow.

Setting clientType is required because there are slight differences between "oauth-app" and "github-app". Most importantly, GitHub Apps do not support scopes.

1const { data, authentication } = await exchangeWebFlowCode({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  code: "code123",
6  scopes: ["repo"],
7});

data is the raw response data. authentication is a User Authentication object.

OAuth Device Flow

In step 1 of GitHub's OAuth Device Flow, you need to create a device and user code

1const {
2  data: { device_code, user_code, verification_uri },
3} = await createDeviceCode({
4  clientType: "oauth-app",
5  clientId: "1234567890abcdef1234",
6  scopes: ["repo"],
7});

In step 2 of GitHub's OAuth Device Flow, the user has to enter user_code on verification_uri (https://github.com/login/device unless you use GitHub Enterprise Server).

Once the user entered the code and granted access, you can exchange the device_code for a user access token in step 3 of GitHub's OAuth Device Flow

1const { data, authentication } = await exchangeDeviceCode({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  code: device_code,
5});

data is the raw response data. authentication is a User Authentication object.

Methods

getWebFlowAuthorizationUrl()

This is a wrapper around @octokit/oauth-authorization-url that accepts a request option instead of baseUrl for consistency with the other OAuth methods. getWebFlowAuthorizationUrl() is a synchronous method and does not send any request.

1const { url } = getWebFlowAuthorizationUrl({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  scopes: ["repo"],
5});

Options

1import { request } from "@octokit-next/request";
2const { url } = getWebFlowAuthorizationUrl({
3  clientType: "oauth-app",
4  clientId: "1234567890abcdef1234",
5  scopes: ["repo"],
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

The getWebFlowAuthorizationUrl method is synchronous and returns an object with the following properties.

exchangeWebFlowCode()

1const { data, authentication } = await exchangeWebFlowCode({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  code: "code123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await exchangeWebFlowCode({
3  clientType: "oauth-app",
4  clientId: "1234567890abcdef1234",
5  clientSecret: "1234567890abcdef12347890abcdef12345678",
6  code: "code123",
7  request: request.defaults({
8    baseUrl: "https://ghe.my-company.com/api/v3",
9  }),
10});

Resolves with an @octokit/request response object for POST /login/oauth/access_token (JSON) with an additional authentication key which is the authentication object.

createDeviceCode()

1const { data, authentication } = await createDeviceCode({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  scopes: ["repo"],
5});

Options

1import { request } from "@octokit-next/request";
2const { data } = await createDeviceCode({
3  clientType: "oauth-app",
4  clientId: "1234567890abcdef1234",
5  scopes: ["repo"],
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

Resolves with an @octokit/request response object for POST https://github.com/login/device/code (JSON).

exchangeDeviceCode()

1const { data, authentication } = await exchangeDeviceCode({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  code: "code123",
5});

1import { request } from "@octokit-next/request";
2const { data, authentication } = await exchangeDeviceCode({
3  clientType: "oauth-app",
4  clientId: "1234567890abcdef1234",
5  code: "code123",
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

checkToken()

1const { data, authentication } = await checkToken({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await checkToken({
3  clientType: "oauth-app",
4  clientId: "1234567890abcdef1234",
5  clientSecret: "1234567890abcdef12347890abcdef12345678",
6  token: "usertoken123",
7  request: request.defaults({
8    baseUrl: "https://ghe.my-company.com/api/v3",
9  }),
10});

Resolves with an @octokit/request response object for POST /applications/{client_id}/token with an additional authentication key which is the authentication object. Note that the authentication object will not include the keys for expiring authentication.

refreshToken()

Expiring user access tokens are currently in preview. You can enable them for any of your GitHub apps. OAuth Apps do not support expiring user access tokens

When a user access token expires it can be refreshed using a refresh token. Refreshing a token invalidates the current user access token.

1const { data, authentication } = await refreshToken({
2  clientType: "github-app",
3  clientId: "lv1.1234567890abcdef",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  refreshToken: "r1.refreshtoken123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await refreshToken({
3  clientType: "github-app",
4  clientId: "lv1.1234567890abcdef",
5  clientSecret: "1234567890abcdef12347890abcdef12345678",
6  refreshToken: "r1.refreshtoken123",
7  request: request.defaults({
8    baseUrl: "https://ghe.my-company.com/api/v3",
9  }),
10});

Resolves with an @octokit/request response object for POST /login/oauth/access_token with an additional authentication key which is the GitHub App expiring user authentication.

scopeToken()

1const { data, authentication } = await scopeToken({
2  clientType: "github-app",
3  clientId: "lv1.1234567890abcdef",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6  target: "octokit",
7  repositories: ["oauth-methods.js"],
8  permissions: {
9    issues: "write",
10  },
11});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await scopeToken({
3  clientType: "github-app",
4  clientId: "lv1.1234567890abcdef",
5  token: "usertoken123",
6  target: "octokit",
7  repositories: ["oauth-methods.js"],
8  permissions: {
9    issues: "write",
10  },
11  request: request.defaults({
12    baseUrl: "https://ghe.my-company.com/api/v3",
13  }),
14});

Resolves with an @octokit/request response object for POST /applications/{client_id}/token/scoped with an additional authentication key which is the new authentication object.

resetToken()

1const { data, authentication } = await resetToken({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await resetToken({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "secret",
5  token: "usertoken123",
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

Resolves with an @octokit/request response object for POST /applications/{client_id}/token with an additional authentication key which is the new authentication object.

deleteToken()

1const { status } = await deleteToken({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await deleteToken({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "secret",
5  token: "usertoken123",
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

Resolves with an @octokit/request response object for DELETE /applications/{client_id}/token (which is an empty 204 response).

deleteAuthorization()

1const { status } = await deleteAuthorization({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef12347890abcdef12345678",
5  token: "usertoken123",
6});

Options

1import { request } from "@octokit-next/request";
2const { data, authentication } = await deleteAuthorization({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "secret",
5  token: "usertoken123",
6  request: request.defaults({
7    baseUrl: "https://ghe.my-company.com/api/v3",
8  }),
9});

Resolves with an @octokit/request response object for DELETE /applications/{client_id}/grant (which is an empty 204 response).

Authentication object

The authentication object returned by the methods have one of three formats.

1. OAuth APP authentication token
2. GitHub APP non-expiring user authentication token with expiring disabled
3. GitHub APP user authentication token with expiring enabled

The differences are

1. scopes is only present for OAuth Apps
2. refreshToken, expiresAt, refreshTokenExpiresAt are only present for GitHub Apps, and only if token expiration is enabled

Note that the clientSecret may not be set when using exchangeDeviceCode() as clientSecret is not required for the OAuth device flow.

OAuth APP authentication

GitHub App with non-expiring user authentication

GitHub App with expiring user authentication

Types

1import {
2  OAuthAppAuthentication,
3  GitHubAppAuthenticationWithExpirationDisabled,
4  GitHubAppAuthenticationWithExpirationEnabled,
5  GitHubAppAuthenticationWithExpiration,
6  GetWebFlowAuthorizationUrlOAuthAppOptions,
7  GetWebFlowAuthorizationUrlGitHubAppOptions,
8  GetWebFlowAuthorizationUrlOAuthAppResult,
9  GetWebFlowAuthorizationUrlGitHubAppResult,
10  CheckTokenOptions,
11  CheckTokenOAuthAppOptions,
12  CheckTokenGitHubAppOptions,
13  CheckTokenResponse,
14  CheckTokenOAuthAppResponse,
15  CheckTokenGitHubAppResponse,
16  ExchangeWebFlowCodeOptions,
17  ExchangeWebFlowCodeOAuthAppOptions,
18  ExchangeWebFlowCodeGitHubAppOptions,
19  ExchangeWebFlowCodeResponse,
20  ExchangeWebFlowCodeOAuthAppResponse,
21  ExchangeWebFlowCodeGitHubAppResponse,
22  CreateDeviceCodeOptions,
23  CreateDeviceCodeOAuthAppOptions,
24  CreateDeviceCodeGitHubAppOptions,
25  CreateDeviceCodeDeviceTokenResponse,
26  ExchangeDeviceCodeOptions,
27  ExchangeDeviceCodeOAuthAppOptionsWithoutClientSecret,
28  ExchangeDeviceCodeOAuthAppOptions,
29  ExchangeDeviceCodeGitHubAppOptionsWithoutClientSecret,
30  ExchangeDeviceCodeGitHubAppOptions,
31  ExchangeDeviceCodeResponse,
32  ExchangeDeviceCodeOAuthAppResponse,
33  ExchangeDeviceCodeOAuthAppResponseWithoutClientSecret,
34  ExchangeDeviceCodeGitHubAppResponse,
35  ExchangeDeviceCodeGitHubAppResponseWithoutClientSecret,
36  RefreshTokenOptions,
37  RefreshTokenResponse,
38  ScopeTokenOptions,
39  ScopeTokenResponse,
40  ResetTokenOptions,
41  ResetTokenOAuthAppOptions,
42  ResetTokenGitHubAppOptions,
43  ResetTokenResponse,
44  ResetTokenOAuthAppResponse,
45  ResetTokenGitHubAppResponse,
46  DeleteTokenOptions,
47  DeleteTokenOAuthAppOptions,
48  DeleteTokenGitHubAppOptions,
49  DeleteTokenResponse,
50  DeleteAuthorizationOptions,
51  DeleteAuthorizationOAuthAppOptions,
52  DeleteAuthorizationGitHubAppOptions,
53  DeleteAuthorizationResponse,
54} from "@octokit-next/oauth-methods";

Contributing

See CONTRIBUTING.md

License

MIT