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

Example usage

<script type="module">
  import {
    createAppAuth,
    createOAuthAppAuth,
    createTokenAuth,
  } from "https://cdn.skypack.dev/@octokit/auth";
</script>

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

token

-

{
  type: "token",
  token: "secret123",
  tokenType, "oauth" // or "installation"
}

{
  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'
}

{
  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: []
}

-

-

{
  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.

License

MIT