⚠️ Deprecation warning

Authentication using a username and password has been deprecated by GitHub on February 14, 2020.

It will be removed entirely on November 13, 2020. Brownouts are scheduled for September 30, 2020 and October 28, 2020.

See the official deprecation announcement for more details.

auth-basic.js

GitHub API Basic authentication for browsers and Node.js

@octokit/auth-basic is implementing one of GitHub’s authentication strategies: authenticating using username and password.

• Usage
• createBasicAuth() options
• auth() options
• auth() result
  • Personal access token authentication
  • OAuth access token authentication
  • Basic authentication result
• auth.hook(request, route, options) or auth.hook(request, options)
• Implementation details
• License

Usage

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

Get token or basic authentication using the auth() method.

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 tokenAuthentication = await auth({
  type: "token",
});

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

Authenticate request using auth.hook()

const { hook } = 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 requestWithAuth = request.defaults({ request: { hook } });

const authorizations = await requestWithAuth("GET /authorizations");

All strategy options

const auth = createBasicAuth({
  username: "octocat",
  password: "secret",
  async on2Fa() {
    return prompt("Two-factor authentication Code:");
  },
  token: {
    note: "octokit 2019-04-03 abc4567",
    scopes: [],
    noteUrl: "https://github.com/octokit/auth.js#basic-auth",
    fingerprint: "abc4567",
    clientId: "1234567890abcdef1234",
    clientSecret: "1234567890abcdef1234567890abcdef12345678",
  },
  request: request.defaults({
    baseUrl: "https://ghe.my-company.com/api/v3",
  }),
});

createBasicAuth() options

name	type	description
username	string	Required. Username of the account to login with.
password	string	Required. Password of the account to login with.
on2Fa	function	Required. If the user has two-factor authentication (2FA) enabled, the on2Fa method will be called and expected to return a time-based one-time password (TOTP) which the user retrieves either via SMS or an authenticator app, based on their account settings. You can pass an empty function if you are certain the account has 2FA disabled. Alias: on2fa
token	object	An object matching "Create a new authorization" parameters, but camelCased.
token.note	string	A note to remind you what the OAuth token is for. Personal access tokens must have a unique note. Attempting to create a token with with an existing note results in a 409 conflict error. Defaults to "octokit <timestamp> <fingerprint>", where <timestamp> has the format YYYY-MM-DD and <fingerprint> is a random string. Example: "octokit 2019-04-03 abc4567".
token.scopes	array of strings	A list of scopes that this authorization is in. See available scopes Defaults to an empty array
token.noteUrl	string	A URL to remind you what app the OAuth token is for. Defaults to "https://github.com/octokit/auth-basic.js#readme"
token.fingerprint	string	A unique string to distinguish an authorization from others created for the same client ID and user. Defaults to a random string
token.clientId	string	The 20 character OAuth app client key for which to create the token.
token.clientSecret	string	The 40 character OAuth app client secret for which to create the token. Note: do not share an OAuth app’s client secret with an untrusted client such as a website or native app.
request	function	You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the hostname + /api/v3. Example: const { request } = require("@octokit/request"); createAppAuth({ clientId: 123, clientSecret: "secret", request: request.defaults({ baseUrl: "https://ghe.my-company.com/api/v3", }), });

auth() options

name	type	description
type	string	Either "basic" or "token". Defaults to "token".
refresh	boolean	If set to true, a new token is created and cached. Only relevent if type is set to "token". Defaults to false.

auth() result

There are three possible results that the async auth() method can resolve to

1. A personal access token authentication
   auth({type: 'token'}) and basic.token.clientId / basic.token.clientSecret not passed as strategy options.
2. An OAuth access token authentication
   auth({type: 'token'}) and basic.token.clientId / basic.token.clientSecret passed as strategy options.
3. Basic authentication
   auth({type: 'basic'})

Personal access token authentication

name	type	description
type	string	"token"
tokenType	string	"pat"
token	string	The personal access token
id	number	Database ID of token
username	string	Username of authenticated user
scopes	array of strings	array of scope names

OAuth access token authentication

name	type	description
type	string	"token"
tokenType	string	"oauth"
token	string	The oauth access token
username	string	Username of authenticated user
id	number	Database ID of token
appClientId	number	OAuth application’s client ID
scopes	array of strings	array of scope names

Basic authentication result

name	type	description
type	string	"basic"
username	string	The decoded username
password	string	The decoded password
credentials	string	base64-encoded string that can be used in Authorization header.
totp	string	The time-based one-time password returned by options.on2Fa(). Only present if 2Fa authentication is enabled for the account.

auth.hook(request, route, options) or auth.hook(request, options)

auth.hook() hooks directly into the request life cycle. It authenticates the request using either basic authentication or a token based on the request URL and handles two-factor authentication with request retries.

The request option is an instance of @octokit/request. The route/options parameters are the same as for the request() method.

auth.hook() can be called directly to send an authenticated request

const { data: authorizations } = await auth.hook(
  request,
  "GET /authorizations"
);

Or it can be passed as option to request().

const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
});

const { data: authorizations } = await requestWithAuth("GET /authorizations");

The on2Fa() method passed as strategy option is (re-)called as needed.request() method

Implementation details

GitHub recommends to use basic authentication only for managing personal access tokens. By default, the auth.hook() method implements this best practice and retrieves a personal access token to authenticate requests. All personal access tokens must have a unique note / fingerprint. The auth() method is setting a defaults that are always different to avoid conflicts. But if you set a custom token.note option, fingerprint is not set to a random string by default in order to avoid multiple tokens with the same note.

Some endpoint however do require basic authentication, such as List your authorizations or Delete an authorization. The auth.hook() method is setting the correct authorization automatically based on the request URL.

There is a special case if the user enabled two-factor authentication with SMS as method, because an SMS with the time-based one-time password (TOTP) will only be sent if a request is made to one of these endpoints

• POST /authorizations - Create a new authorization
• PUT /authorizations/clients/:client_id - Get-or-create an authorization for a specific app
• PUT /authorizations/clients/:client_id/:fingerprint - Get-or-create an authorization for a specific app and fingerprint
• PATCH /authorizations/:authorization_id - Update an existing authorization

To guarantee the TOTP delivery via SMS, auth.hook() is sending an additional request which has no other effect.

License

MIT