@octokit/auth v3.0.3
auth.js
GitHub API authentication library for browsers and Node.js
GitHub supports 4 authentication strategies. They are all implemented in @octokit/auth
.
Example usage
Load @octokit/auth
directly from cdn.skypack.dev
<script type="module">
import {
createAppAuth,
createOAuthAppAuth,
createTokenAuth,
} from "https://cdn.skypack.dev/@octokit/auth";
</script>
Install with npm install @octokit/auth
const {
createAppAuth,
createOAuthAppAuth,
createTokenAuth,
createActionAuth,
} = require("@octokit/auth");
// or:
// import {
// createAppAuth,
// createOAuthAppAuth,
// createTokenAuth,
// createActionAuth
// } from "@octokit/auth";
const auth = createAppAuth({
appId: 12345,
privateKey: "...",
});
Each function exported by @octokit/auth
returns an async auth
function.
The auth
function resolves with an authentication object. If multiple authentication types are supported, a type
parameter can be passed.
const { token } = await auth({ type: "app" });
Additionally, auth.hook()
can be used to directly hook into @octokit/request
. If multiple authentication types are supported, the right authentication type will be applied automatically based on the request URL.
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});
const { data: authorizations } = await requestWithAuth("GET /authorizations");
Official Strategies
Comparison
@octokit/auth-token
token
-
{
type: "token",
token: "secret123",
tokenType, "oauth" // or "installation"
}
@octokit/auth-app
{
id*,
privateKey*,
installationId,
cache,
request
}
{
type*, // "app" or "installation"
installationId,
repositoryIds,
permissions,
refresh
}
{
type: "app",
token: "abc.def.1234",
appId: 123,
expiresAt: "2019-06-11T22:22:34Z"
}
{
type: "token",
tokenType: "installation",
token: "v1.secret123",
installationId: 1234,
expiresAt: "2019-06-11T22:22:34Z",
repositoryIds: [12345],
permissions: {
single_file: 'write'
},
singleFileName: '.github/myapp.yml'
}
@octokit/auth-oauth-app
{
clientId*,
clientSecret*,
code,
redirectUrl,
state,
request
}
{
type*, // "oauth-app" or "token"
url
}
{
type: "oauth-app",
clientId: "abc123",
clientSecret: "abc123secret",
headers: {},
query: {
clientId: "abc123",
clientSecret: "abc123secret"
}
}
{
type: "token",
tokenType: "oauth",
token: "123secret",
scopes: []
}
@octokit/auth-action
-
-
{
type: "token",
tokenType: "installation",
token: "v1.123secret"
}
Token authentication
Example
const auth = createTokenAuth("1234567890abcdef1234567890abcdef12345678");
const { token, tokenType } = await auth();
See @octokit/auth-token for more details.
GitHub App or installation authentication
Example
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN RSA PRIVATE KEY-----\n...",
});
const appAuthentication = await auth({ type: "auth" });
const installationAuthentication = await auth({
type: "installation",
installationId: 123,
});
See @octokit/auth-app for more details.
OAuth app and OAuth access token authentication
Example
const auth = createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "random123", // code from OAuth web flow, see https://git.io/fhd1D
});
const appAuthentication = await auth({
type: "oauth-app",
url: "/orgs/{org}/repos",
});
const tokenAuthentication = await auth({ type: "token" });
See @octokit/auth-oauth-app for more details.
GitHub Action authentication
Example
// expects process.env.GITHUB_ACTION and process.env.GITHUB_TOKEN to be set
const auth = createActionAuth();
const { token } = await auth();
See @octokit/auth-action for more details.
Community Strategies
.netrc authentication
Similar to token authentication, but reads the token from your ~/.netrc
file
Example
// expects a personal access token to be set as `login` in the `~/.netrc` file for `api.github.com`
const { createNetrcAuth } = require("octokit-netrc-auth");
const auth = createNetrcAuth();
const { token } = await auth();
See octokit-auth-netrc for more details.