@octokit-next/oauth-methods
v2.8.0
Published
Set of stateless request methods to create, check, reset, refresh, and delete user access tokens for OAuth and GitHub Apps
Downloads
11
Readme
oauth-methods.js
Set of stateless request methods to create, check, reset, refresh, and delete user access tokens for OAuth and GitHub Apps
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
Browsers
@octokit-next/oauth-methods
is not meant for browser usage.
Some of the methods will work, but others do not have CORS headers enabled and will fail (exchangeWebFlowCode()
, createDeviceCode()
, exchangeDeviceCode()
, refreshToken()
). Also the Client Secret should not be exposed to clients as it can be used for a Person-in-the-middle attack.
Node
Install with npm install @octokit/core @octokit-next/oauth-methods
import {
exchangeWebFlowCode,
createDeviceCode,
exchangeDeviceCode,
checkToken,
refreshToken,
scopeToken,
resetToken,
deleteToken,
deleteAuthorization,
} from ("@octokit-next/oauth-methods");
Deno
Load @octokit-next/oauth-methods directly from cdn.skypack.dev, including types.
import {
exchangeWebFlowCode,
createDeviceCode,
exchangeDeviceCode,
checkToken,
refreshToken,
scopeToken,
resetToken,
deleteToken,
deleteAuthorization,
} 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.
const { data, authentication } = await exchangeWebFlowCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
code: "code123",
scopes: ["repo"],
});
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
const {
data: { device_code, user_code, verification_uri },
} = await createDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["repo"],
});
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
const { data, authentication } = await exchangeDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
code: device_code,
});
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.
const { url } = getWebFlowAuthorizationUrl({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["repo"],
});
Options
Only relevant if clientType
is set to "oauth-app"
.
An array of scope names (or: space-delimited list of scopes). If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
Defaults to []
.
import { request } from "@octokit-next/request";
const { url } = getWebFlowAuthorizationUrl({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["repo"],
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
The getWebFlowAuthorizationUrl
method is synchronous and returns an object with the following properties.
Only set if options.clientType
is set to "oauth-app"
.
Returns an array of strings. Returns options.scopes if it was set and turns the string into an array if a string was passed, otherwise [].
exchangeWebFlowCode()
const { data, authentication } = await exchangeWebFlowCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
code: "code123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await exchangeWebFlowCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
code: "code123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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()
const { data, authentication } = await createDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["repo"],
});
Options
Only permitted if clientType
is set to "oauth-app"
. GitHub Apps do not support scopes.
Array of scope names you want to request for the user access token.
import { request } from "@octokit-next/request";
const { data } = await createDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["repo"],
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
Resolves with an @octokit/request
response object for POST https://github.com/login/device/code
(JSON).
exchangeDeviceCode()
const { data, authentication } = await exchangeDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
code: "code123",
});
import { request } from "@octokit-next/request";
const { data, authentication } = await exchangeDeviceCode({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
code: "code123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
checkToken()
const { data, authentication } = await checkToken({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await checkToken({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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.
const { data, authentication } = await refreshToken({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12347890abcdef12345678",
refreshToken: "r1.refreshtoken123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await refreshToken({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12347890abcdef12345678",
refreshToken: "r1.refreshtoken123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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()
const { data, authentication } = await scopeToken({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
target: "octokit",
repositories: ["oauth-methods.js"],
permissions: {
issues: "write",
},
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await scopeToken({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
token: "usertoken123",
target: "octokit",
repositories: ["oauth-methods.js"],
permissions: {
issues: "write",
},
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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()
const { data, authentication } = await resetToken({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await resetToken({
clientId: "1234567890abcdef1234",
clientSecret: "secret",
token: "usertoken123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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()
const { status } = await deleteToken({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await deleteToken({
clientId: "1234567890abcdef1234",
clientSecret: "secret",
token: "usertoken123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
Resolves with an @octokit/request
response object for DELETE /applications/{client_id}/token
(which is an empty 204
response).
deleteAuthorization()
const { status } = await deleteAuthorization({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12347890abcdef12345678",
token: "usertoken123",
});
Options
import { request } from "@octokit-next/request";
const { data, authentication } = await deleteAuthorization({
clientId: "1234567890abcdef1234",
clientSecret: "secret",
token: "usertoken123",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
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.
- OAuth APP authentication token
- GitHub APP non-expiring user authentication token with expiring disabled
- GitHub APP user authentication token with expiring enabled
The differences are
scopes
is only present for OAuth AppsrefreshToken
,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
import {
OAuthAppAuthentication,
GitHubAppAuthenticationWithExpirationDisabled,
GitHubAppAuthenticationWithExpirationEnabled,
GitHubAppAuthenticationWithExpiration,
GetWebFlowAuthorizationUrlOAuthAppOptions,
GetWebFlowAuthorizationUrlGitHubAppOptions,
GetWebFlowAuthorizationUrlOAuthAppResult,
GetWebFlowAuthorizationUrlGitHubAppResult,
CheckTokenOptions,
CheckTokenOAuthAppOptions,
CheckTokenGitHubAppOptions,
CheckTokenResponse,
CheckTokenOAuthAppResponse,
CheckTokenGitHubAppResponse,
ExchangeWebFlowCodeOptions,
ExchangeWebFlowCodeOAuthAppOptions,
ExchangeWebFlowCodeGitHubAppOptions,
ExchangeWebFlowCodeResponse,
ExchangeWebFlowCodeOAuthAppResponse,
ExchangeWebFlowCodeGitHubAppResponse,
CreateDeviceCodeOptions,
CreateDeviceCodeOAuthAppOptions,
CreateDeviceCodeGitHubAppOptions,
CreateDeviceCodeDeviceTokenResponse,
ExchangeDeviceCodeOptions,
ExchangeDeviceCodeOAuthAppOptionsWithoutClientSecret,
ExchangeDeviceCodeOAuthAppOptions,
ExchangeDeviceCodeGitHubAppOptionsWithoutClientSecret,
ExchangeDeviceCodeGitHubAppOptions,
ExchangeDeviceCodeResponse,
ExchangeDeviceCodeOAuthAppResponse,
ExchangeDeviceCodeOAuthAppResponseWithoutClientSecret,
ExchangeDeviceCodeGitHubAppResponse,
ExchangeDeviceCodeGitHubAppResponseWithoutClientSecret,
RefreshTokenOptions,
RefreshTokenResponse,
ScopeTokenOptions,
ScopeTokenResponse,
ResetTokenOptions,
ResetTokenOAuthAppOptions,
ResetTokenGitHubAppOptions,
ResetTokenResponse,
ResetTokenOAuthAppResponse,
ResetTokenGitHubAppResponse,
DeleteTokenOptions,
DeleteTokenOAuthAppOptions,
DeleteTokenGitHubAppOptions,
DeleteTokenResponse,
DeleteAuthorizationOptions,
DeleteAuthorizationOAuthAppOptions,
DeleteAuthorizationGitHubAppOptions,
DeleteAuthorizationResponse,
} from "@octokit-next/oauth-methods";
Contributing
See CONTRIBUTING.md