JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 3392
  • Score
    100M100P100Q41519F
  • License MIT

GitHub API authentication library for browsers and Node.js

Package Exports

  • @octokit/auth

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@octokit/auth) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

auth.js

GitHub API authentication library for browsers and Node.js

@latest Build Status Greenkeeper

GitHub supports 4 authentication strategies. They are all implemented in @octokit/auth.

Example usage

Browsers

Load @octokit/auth directly from cdn.pika.dev

<script type="module">
  import {
    createBasicAuth,
    createAppAuth,
    createOAuthAppAuth,
    createTokenAuth
  } from "https://cdn.pika.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");

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,
  expriseAt: "2019-06-11T22:22:34Z"
}
 
{
  type: "token",
  tokenType: "installation",
  token: "v1.secret123",
  installationId: 1234,
  expriseAt: "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.

License

MIT