Gathering detailed insights and metrics for @octokit/oauth-methods
Gathering detailed insights and metrics for @octokit/oauth-methods
Request methods to create and refresh user access tokens for OAuth and GitHub Apps
Installations
npm install @octokit/oauth-methodsDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Min. Node Version
>= 20
Node Version
22.15.0
NPM Version
10.9.2
Score
98.8
Supply Chain
99.5
Quality
81.6
Maintenance
100
Vulnerability
100
License
Releases
33
Languages
2
TypeScript
JavaScript
TypeScript (96.73%)
JavaScript (3.27%)
Developer
octokit
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
9 Stars
347 Commits
11 Forks
4 Watchers
6 Branches
19 Contributors
Updated on May 30, 2025
Maintainers
1
Package Meta Information
Latest Version
6.0.0
Package Id
@octokit/oauth-methods@6.0.0
Unpacked Size
92.28 kB
Size
12.68 kB
File Count
32
NPM Version
10.9.2
Node Version
22.15.0
Published on
May 20, 2025
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
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 |
Some of the methods will work, but others do not have CORS headers enabled and will fail ( |
|---|---|
|
Node |
Install with
|
[!IMPORTANT] As we use conditional exports, you will need to adapt your
tsconfig.jsonby setting"moduleResolution": "node16", "module": "node16".See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus
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
| name | type | description |
|---|---|---|
clientId
|
string
| Required. The client ID you received from GitHub when you registered. |
clientType
|
string
|
Required. Must be set to either "oauth-app" or "github-app".
|
redirectUrl
|
string
| The URL in your application where users will be sent after authorization. See Redirect URLs in GitHub’s Developer Guide. |
login
|
string
| Suggests a specific account to use for signing in and authorizing the app. |
scopes
|
array of strings
|
Only relevant if 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 |
state
|
string
|
An unguessable random string. It is used to protect against cross-site request forgery attacks.
Defaults to Math.random().toString(36).substr(2).
|
allowSignup
|
boolean
|
Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. Use false in the case that a policy prohibits signups. Defaults to true.
|
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
The getWebFlowAuthorizationUrl method is synchronous and returns an object with the following properties.
| name | type | description |
|---|---|---|
allowSignup
|
boolean
|
Returns options.allowSignup if it was set. Defaults to true.
|
clientType
|
string
|
Returns options.clientType
|
clientId
|
string
|
Returns options.clientId.
|
login
|
string
|
Returns options.login if it was set. Defaults to null.
|
redirectUrl
|
string
|
Returns options.redirectUrl if it was set. Defaults to null.
|
scopes
|
array of strings
|
Only set if Returns an array of strings. Returns |
state
|
string
|
Returns options.state if it was set. Defaults to Math.random().toString(36).substr(2).
|
url
|
string
| The authorization URL |
exchangeWebFlowCode()
1const { data, authentication } = await exchangeWebFlowCode({ 2 clientType: "oauth-app", 3 clientId: "1234567890abcdef1234", 4 clientSecret: "1234567890abcdef12347890abcdef12345678", 5 code: "code123", 6});
Options
| name | type | description |
|---|---|---|
clientType
|
string
|
Required. Must be set to either "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
code
|
string
|
Required. The code from GitHub's OAuth flow redirect's ?code=... query parameter
|
redirectUrl
|
string
|
The redirectUrl option you passed to getWebFlowAuthorizationUrl()
|
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Required. Must be set to either "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
scopes
|
array of strings
|
Only permitted if Array of scope names you want to request for the user access token. |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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});
| name | type | description |
|---|---|---|
clientType
|
string
|
Required. Must be set to either "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
code
|
string
|
Required. The device_code from the createDeviceCode() response
|
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
checkToken()
1const { data, authentication } = await checkToken({ 2 clientType: "oauth-app", 3 clientId: "1234567890abcdef1234", 4 clientSecret: "1234567890abcdef12347890abcdef12345678", 5 token: "usertoken123", 6});
Options
| name | type | description |
|---|---|---|
clientType
|
string
|
Required. Must be set to either "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
token
|
string
| Required. The user access token to check |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Must be set to "github-app"
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
refreshToken
|
string
| Required. The refresh token that was received alongside the user access token. |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Required. Must be set to "github-app".
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
target
|
string
|
Required unless targetId is set. The name of the user or organization to scope the user-to-server access token to.
|
targetId
|
integer
|
Required unless target is set. The ID of the user or organization to scope the user-to-server access token to.
|
repositories
|
array of strings
|
The list of repository names to scope the user-to-server access token to. repositories may not be specified if repository_ids is specified.
|
repository_ids
|
array of integers
|
The list of repository IDs to scope the user-to-server access token to. repositories may not be specified if repositories is specified.
|
permissions
|
object
| The permissions granted to the user-to-server access token. See GitHub App Permissions. |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Must be set to "oauth-app" or "github-app".
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
token
|
string
| Required. The user access token to reset |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Must be set to "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
token
|
string
| Required. The user access token to delete |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
| name | type | description |
|---|---|---|
clientType
|
string
|
Must be set to "oauth-app" or "github-app"
|
clientId
|
string
| Required. Your app's client ID |
clientSecret
|
string
| Required. One of your app's client secrets |
token
|
string
| Required. A valid user access token for the authorization |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the REST API root endpoint. Example:
|
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
scopesis only present for OAuth AppsrefreshToken,expiresAt,refreshTokenExpiresAtare 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
| name | type | description |
|---|---|---|
clientType
|
string
|
"oauth-app"
|
clientId
|
string
|
The app's Client ID
|
token
|
string
| The user access token |
scopes
|
array of strings
| array of scope names enabled for the token |
GitHub App with non-expiring user authentication
| name | type | description |
|---|---|---|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
token
|
string
| The user access token |
GitHub App with expiring user authentication
| name | type | description |
|---|---|---|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
token
|
string
| The user access token |
refreshToken
|
string
| The refresh token |
expiresAt
|
string
|
Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
|
refreshTokenExpiresAt
|
string
|
Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z
|
Types
1import { 2 OAuthAppAuthentication, 3 GitHubAppAuthentication, 4 GitHubAppAuthenticationWithExpiration, 5 GetWebFlowAuthorizationUrlOAuthAppOptions, 6 GetWebFlowAuthorizationUrlGitHubAppOptions, 7 GetWebFlowAuthorizationUrlOAuthAppResult, 8 GetWebFlowAuthorizationUrlGitHubAppResult, 9 CheckTokenOAuthAppOptions, 10 CheckTokenGitHubAppOptions, 11 CheckTokenOAuthAppResponse, 12 CheckTokenGitHubAppResponse, 13 ExchangeWebFlowCodeOAuthAppOptions, 14 ExchangeWebFlowCodeGitHubAppOptions, 15 ExchangeWebFlowCodeOAuthAppResponse, 16 ExchangeWebFlowCodeGitHubAppResponse, 17 CreateDeviceCodeOAuthAppOptions, 18 CreateDeviceCodeGitHubAppOptions, 19 CreateDeviceCodeDeviceTokenResponse, 20 ExchangeDeviceCodeOAuthAppOptionsWithoutClientSecret, 21 ExchangeDeviceCodeOAuthAppOptions, 22 ExchangeDeviceCodeGitHubAppOptionsWithoutClientSecret, 23 ExchangeDeviceCodeGitHubAppOptions, 24 ExchangeDeviceCodeOAuthAppResponse, 25 ExchangeDeviceCodeOAuthAppResponseWithoutClientSecret, 26 ExchangeDeviceCodeGitHubAppResponse, 27 ExchangeDeviceCodeGitHubAppResponseWithoutClientSecret, 28 RefreshTokenOptions, 29 RefreshTokenResponse, 30 ScopeTokenOptions, 31 ScopeTokenResponse, 32 ResetTokenOAuthAppOptions, 33 ResetTokenGitHubAppOptions, 34 ResetTokenOAuthAppResponse, 35 ResetTokenGitHubAppResponse, 36 DeleteTokenOAuthAppOptions, 37 DeleteTokenGitHubAppOptions, 38 DeleteTokenResponse, 39 DeleteAuthorizationOAuthAppOptions, 40 DeleteAuthorizationGitHubAppOptions, 41 DeleteAuthorizationResponse, 42} from "@octokit/oauth-methods";
Contributing
See CONTRIBUTING.md
License
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
all changesets reviewed
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:17
Reason
SAST tool detected but not run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Warn: 28 commits out of 30 are checked with a SAST tool
Reason
1 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
Reason
dependency not pinned by hash detected -- score normalized to 5
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/add_to_octokit_project.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/add_to_octokit_project.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/codeql-analysis.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:72: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/codeql-analysis.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/immediate-response.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/immediate-response.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/release.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/update-prettier.yml/main?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/oauth-methods.js/update-prettier.yml/main?enable=pin
- Info: 4 out of 11 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 2 third-party GitHubAction dependencies pinned
- Info: 3 out of 3 npmCommand dependencies pinned
Reason
3 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 2
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:28
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:29
- Warn: no topLevel permission defined: .github/workflows/add_to_octokit_project.yml:1
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:11
- Warn: no topLevel permission defined: .github/workflows/test.yml:1
- Warn: no topLevel permission defined: .github/workflows/update-prettier.yml:1
- Info: no jobLevel write permissions found
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Score
6.2
/10
Last Scanned on 2025-07-07
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More