@octokit/auth-app

@octokit/auth-app implements the full range of GitHub App authentication flows for JavaScript: signing JSON Web Tokens for app-level requests, exchanging them for per-installation access tokens, and handling OAuth user-to-server token flows (web and device). It is designed to be used standalone or plugged directly into Octokit as an auth strategy.

Maintained by the official Octokit organization, it automatically caches and refreshes installation tokens, exposes a hook() for transparent request authentication, and ships full TypeScript types for every authentication object it returns.

What You Get

• createAppAuth() factory implementing GitHub App JWT authentication
• Installation access token retrieval and automatic in-memory caching/refresh
• OAuth App (client ID/secret) authentication support
• User-to-server OAuth token flows (web flow and device flow)
• An Octokit-compatible auth.hook() for transparent per-request authentication
• Full TypeScript types for every authentication result object

Common Use Cases

• Authenticating a GitHub App’s backend service to call the GitHub REST/GraphQL API
• Minting short-lived installation tokens for CI bots acting on specific repositories
• Implementing ‘Sign in with GitHub App’ user OAuth flows
• Building admin tooling that needs both app-level and per-installation API access
• Wiring authentication directly into an Octokit client via the auth option

Under The Hood

Architecture - src/index.ts wires together auth.ts (the core createAppAuth factory), get-app-authentication.ts (JWT signing for app-level auth), get-installation-authentication.ts (exchanging a JWT for an installation token via the GitHub API), cache.ts (in-memory token caching keyed by installation), and hook.ts (the Octokit request-hook integration that transparently attaches auth headers) - together forming a strategy object that Octokit’s plugin system consumes uniformly alongside its other auth strategies (auth-oauth-app, auth-oauth-user).

Tech Stack - Pure TypeScript targeting ESM output, built with the shared Octokit build tooling (scripts/build.mjs + tsc), depending on sibling Octokit packages (@octokit/auth-oauth-app, @octokit/auth-oauth-user, @octokit/request) plus universal-github-app-jwt for JWT signing and deprecation/once for small utility concerns - deliberately avoiding a general-purpose JWT library dependency by delegating to a purpose-built one.

Code Quality - Tests run under Vitest with coverage reporting (vitest run --coverage), a pretest lint step enforces Prettier formatting, and a dedicated test:typescript script validates the exported type declarations under strict compiler settings - reflecting the Octokit org’s emphasis on type-correctness for a security-sensitive authentication package.

API Design - A single createAppAuth(options) call returns a callable auth() function whose behavior (JWT vs installation vs OAuth vs user token) is selected by the shape of the arguments passed at call time, which keeps the entry point small; the trade-off is that consumers need the README’s type reference to know which options object produces which authentication result, though TypeScript overloads mitigate this in editors with type-checking.