Package Exports

@octokit/auth-app

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-app) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

auth-app.js

GitHub App authentication for JavaScript

@octokit/auth-app implements one of GitHub’s authentication strategies.

It implements authentication using a JSON Web Token for apps as well as installation access tokens.

Usage

import { request } from "@octokit/request";
import { createAppAuth } from "@octokit/auth-app";

const auth = createAppAuth({
  id: 1,
  privateKey: "-----BEGIN RSA PRIVATE KEY-----\n..."
});

(async () => {
  // Retrieve JSON Web Token (JWT) to authenticate as app
  const appAuthentication = await auth();
  const { data: appDetails } = await request("GET /app", {
    headers: appAuthentication.headers,
    previews: ["machine-man"]
  });

  // Retrieve installation access token
  const installationAuthentication = await auth({ installationId: 123 });
  const { data: repositories } = await request(
    "GET /installation/repositories",
    {
      headers: installationAuthentication.headers,
      previews: ["machine-man"]
    }
  );

  // Retrieve JSON Web Token (JWT) or installation access token based on request url
  const url = "/installation/repositories";
  const authentication = await auth({
    installationId: 123,
    url
  });
  const { data: repositories } = await request(url, {
    headers: authentication.headers,
    previews: ["machine-man"]
  });
})();

Strategy options

name	type	description
`id`	`number`	Required. Find App ID on the app’s about page in settings.
`privateKey`	`string`	Required. Content of the `*.pem` file you downloaded from the app’s about page. You can generate a new private key if needed.
`installationId`	`number`	A default `installationId` to be used when calling `auth()`.
`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" }) });
`cache`	`object`	Installation tokens expire after an hour. By default, `@octokit/auth-app` is caching up to 15000 tokens simultaneously using lru-cache. You can pass your own cache implementation by passing `options.cache.{get,set}` to the constructor. Example: const CACHE = {}; createAppAuth({ clientId: 123, clientSecret: "secret", cache: { get(key) { return CACHE[key]; }, set(key, value) { CACHE[key] = value; } } });

Auth options

name	type	description
`installationId`	`number`	Required if `url`, `repositoryIds` or `permissions` passed, unless a default `installationId` option was passed to `createAppAuth()`. ID of installation to retrieve authentication for.
`repositoryIds`	`array of string`	The `id`s of the repositories that the installation token can access.
`premissions`	`object`	The permissions granted to the access token. The permissions object includes the permission names and their access type. For a complete list of permissions and allowable values, see GitHub App permissions.
`url`	`string`	An absolute URL or endpoint route path. Examples: `"https://enterprise.github.com/api/v3/app"` `"/app/installations/123"` `"/app/installations/:installation_id"` Depending on the `url`, the resulting authentication object is either a JWT or an installation token.
`refresh`	`boolean`	Installation tokens expire after one hour. By default, tokens are cached and returned from cache until expired. To bypass and update a cached token for the given `installationId`, set `refresh` to `true`. Defaults to `false`.

Authentication object

There are two possible results

JSON Web Token (JWT) authentication
❌ installationId was not passed to auth()
✅ url passed to auth() matches an endpoint that requires JWT authentication.
Installation access token authentication
✅ installationId passed to auth()
❌ url passed to auth() does not match an endpoint that requires JWT authentication.

JSON Web Token (JWT) authentication

name	type	description
`type`	`string`	`"app"`
`token`	`string`	The JSON Web Token (JWT) to authenticate as the app.
`appId`	`number`	GitHub App database ID.
`expiration`	`number`	Number of seconds from 1970-01-01T00:00:00Z UTC. A Date object can be created using `new Date(authentication.expiration * 1000)`.
`headers`	`object`	`{ authorization }` - value for the "Authorization" header.
`query`	`object`	`{}` - not used

Installation access token authentication

name	type	description
`type`	`string`	`"token"`
`token`	`string`	The installation access token.
`tokenType`	`string`	`"installation"`
`installationId`	`number`	Installation database ID.
`expiresAt`	`string`	Timestamp in UTC format, e.g. `2019-06-11T22:22:34Z`.
`repositoryIds`	`array of numbers`	Only present if `repositoryIds` option passed to `auth(options)`.
`permissions`	`object`	An object where keys are the permission name and the value is either `"read"` or `"write"`. See the list of all GitHub App Permissions.
`singleFileName`	`string`	If the single file permission is enabled, the `singleFileName` property is set to the path of the accessible file.
`headers`	`object`	`{ authorization }` - value for the "Authorization" header.
`query`	`object`	`{}` - not used

License

MIT