@octokit/auth

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
• Official Strategies
  • Comparison
  • Token authentication
  • Basic and personal access token authentication
  • GitHub App or installation authentication
  • OAuth app and OAuth access token authentication
  • GitHub Action authentication
• Community Strategies
  • .netrc authentication
• License

Example usage

Browsers	Load @octokit/auth directly from cdn.skypack.dev <script type="module"> import { createBasicAuth, createAppAuth, createOAuthAppAuth, createTokenAuth, } from "https://cdn.skypack.dev/@octokit/auth"; </script>
Node	Install with npm install @octokit/auth const { createBasicAuth, createAppAuth, createOAuthAppAuth, createTokenAuth, createActionAuth, } = require("@octokit/auth"); // or: // import { // createBasicAuth, // createAppAuth, // createOAuthAppAuth, // createTokenAuth, // createActionAuth // } from "@octokit/auth";

const auth = createBasicAuth({
  username: "monatheoctocat",
  password: "secret",
  on2Fa() {
    return prompt("Two-factor authentication Code:");
  },
});

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: "token" });

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

Module	Strategy Options	Auth Options	Authentication objects
@octokit/auth-token	token	-	{ type: "token", token: "secret123", tokenType, "oauth" // or "installation" }
@octokit/auth-basic	{ username*, password*, on2Fa*, token, request }	{ type*, // "basic" or "token" refresh }	{ type: "basic" username: "octocat", password: "secret", credentials: "b2N0b2NhdDpzZWNyZXQ=", totp: "123456" }	{ type: "token" tokenType: "pat", token: "secret123", id: 123, username: "octocat", scopes: [] }	{ type: "token" tokenType: "oauth", token: "secret123", id: 123, appClientId: "abc123", username: "octocat", scopes: [] }
@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.

Basic and personal access token authentication

Example

const auth = createBasicAuth({
  username: "octocat",
  password: "secret",
  async on2Fa() {
    // prompt user for the one-time password retrieved via SMS or authenticator app
    return prompt("Two-factor authentication Code:");
  },
});

const { token } = await auth();
const { totp } = await auth({
  type: "basic",
});

See @octokit/auth-basic for more details.

GitHub App or installation authentication

Example

const auth = createAppAuth({
  id: 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.

License

MIT