{"id":14195,"library":"universal-github-app-jwt","title":"Universal GitHub App JWT Generator","description":"universal-github-app-jwt is a JavaScript/TypeScript library designed to securely generate JSON Web Tokens (JWTs) for GitHub Apps. It supports various JavaScript runtimes including Node.js, Deno, and modern web browsers by leveraging the Web Crypto API features or Node's `crypto` module. The current stable version is 2.2.2, with releases occurring as needed for bug fixes and minor features, often multiple times a month, indicating active maintenance and responsiveness. Its key differentiator is its universal compatibility across different environments, simplifying GitHub App authentication by abstracting away the underlying cryptographic implementations. It focuses specifically on generating the app installation token, which is often used in conjunction with other Octokit libraries like `@octokit/auth-app.js` for complete GitHub App authentication flows.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/gr2m/universal-github-app-jwt","tags":["javascript","github","authentication","app","jwt","webcrypto","typescript"],"install":[{"cmd":"npm install universal-github-app-jwt","lang":"bash","label":"npm"},{"cmd":"yarn add universal-github-app-jwt","lang":"bash","label":"yarn"},{"cmd":"pnpm add universal-github-app-jwt","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `githubAppJwt` function is the default export. Use the default import syntax for Node.js or bundled browser environments.","wrong":"import { githubAppJwt } from 'universal-github-app-jwt';","symbol":"githubAppJwt","correct":"import githubAppJwt from 'universal-github-app-jwt';"},{"note":"For Deno and direct browser usage, import directly from a CDN like esm.sh.","wrong":"import githubAppJwt from './node_modules/universal-github-app-jwt';","symbol":"githubAppJwt (Deno/Browser CDN)","correct":"import githubAppJwt from 'https://esm.sh/universal-github-app-jwt';"},{"note":"While primarily an ESM package, if CommonJS is strictly necessary, access the default export via `.default`. ESM `import` is strongly recommended.","wrong":"const githubAppJwt = require('universal-github-app-jwt');","symbol":"githubAppJwt (CommonJS)","correct":"const githubAppJwt = require('universal-github-app-jwt').default;"}],"quickstart":{"code":"import githubAppJwt from 'universal-github-app-jwt';\nimport { request } from '@octokit/request';\n\nconst APP_ID = process.env.GITHUB_APP_ID ?? '';\nconst PRIVATE_KEY = process.env.GITHUB_APP_PRIVATE_KEY ?? '';\n\nasync function authenticateApp() {\n  if (!APP_ID || !PRIVATE_KEY) {\n    throw new Error('GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY environment variables must be set.');\n  }\n\n  try {\n    const { token, appId, expiration } = await githubAppJwt({\n      id: APP_ID,\n      privateKey: PRIVATE_KEY,\n    });\n\n    console.log(`Generated GitHub App JWT for App ID ${appId}. Expires at: ${new Date(expiration * 1000).toISOString()}`);\n    console.log(`Token: ${token.substring(0, 10)}...${token.substring(token.length - 10)}`);\n\n    // Example usage with @octokit/request\n    const appDetails = await request('GET /app', {\n      headers: {\n        authorization: `bearer ${token}`,\n      },\n    });\n    console.log('Successfully fetched App details:', appDetails.data.name);\n  } catch (error) {\n    console.error('Error generating or using JWT:', error);\n  }\n}\n\nauthenticateApp();","lang":"typescript","description":"Demonstrates how to generate a GitHub App JWT using an application ID and private key, then using it to authenticate an `@octokit/request`."},"warnings":[{"fix":"Ensure your private key is in PKCS#8 format. If generated via `ssh-keygen`, convert it using `ssh-keygen -p -m PKCS8 -f app-private-key.pem`. When setting it as an environment variable, ensure line breaks are preserved or correctly escaped if in a single line (though direct file reading is safer).","message":"Private keys must be in PKCS#8 format and maintain original line breaks. Incorrect formatting (e.g., missing newlines, wrong encryption standard) is a common source of errors. Recent versions (>=2.1.1) automatically handle escaped newlines (`\\n`) within the string, but the underlying requirement for a correctly formatted key persists. Consult the package's README for correct `ssh-keygen` options to convert keys to PKCS#8 format.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new applications or those targeting `github.com` or modern GHES (3.14+), prioritize using the GitHub App's Client ID for the `options.id` parameter.","message":"The `options.id` parameter can accept either the GitHub App's numerical ID or its Client ID. For `github.com` and GitHub Enterprise Server (GHES) versions 3.14 and newer, it is recommended to use the Client ID for better alignment with GitHub's authentication practices. Using the App's numerical ID will still work on older or unsupported environments.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"If encountering crypto-related errors in Bun, upgrade to `universal-github-app-jwt@2.2.1` or newer. For other runtimes, ensure Web Crypto API or Node.js `crypto` module is available and properly configured.","message":"When running in Node.js, this library relies on the `node:crypto` module, specifically its `subtle` interface. In Bun, previous versions of this library had issues with `subtle` exports. Ensure you are using a compatible runtime version for full functionality.","severity":"gotcha","affected_versions":"<2.2.1 (Bun)"}],"env_vars":null,"search_vec":"'2.2.2':55 'abstract':92 'across':84 'activ':73 'api':43 'app':3,9,25,89,104,122,128 'authent':90,123,127 'away':93 'browser':37 'bug':62 'compat':83 'complet':120 'conjunct':112 'crypto':42,48 'cryptograph':96 'current':51 'deno':33 'design':15 'differ':85 'differenti':79 'environ':86 'featur':44,66 'fix':63 'flow':124 'focus':99 'generat':5,18,102 'github':2,8,24,88,121,126 'implement':97 'includ':31 'indic':72 'instal':105 'javascript':29,125 'javascript/typescript':13 'json':19 'jwt':4,10,129 'jwts':22 'key':78 'leverag':39 'librari':14,116 'like':117 'mainten':74 'minor':65 'modern':35 'modul':49 'month':71 'multipl':68 'need':60 'node':46 'node.js':32 'occur':58 'octokit':115 'octokit/auth-app.js':118 'often':67,109 'releas':57 'respons':76 'runtim':30 'secur':17 'simplifi':87 'specif':100 'stabl':52 'support':27 'time':69 'token':21,106 'typescript':131 'under':95 'univers':1,7,82 'universal-github-app-jwt':6 'use':110 'various':28 'version':53 'web':20,36,41 'webcrypto':130","created_at":"2026-04-20T01:58:25.944735+00:00","updated_at":"2026-04-20T01:58:25.944735+00:00","problems":[{"fix":"Verify that your private key starts with `-----BEGIN PRIVATE KEY-----` and ends with `-----END PRIVATE KEY-----`. Ensure all line breaks are preserved exactly as in the `.pem` file. If using an environment variable, ensure proper escaping of newlines or read from a file directly. Convert the key to PKCS#8 if necessary (e.g., `ssh-keygen -p -m PKCS8 -f original-key.pem > new-pkcs8-key.pem`).","cause":"The provided private key string is not in the expected PKCS#8 format or has incorrect line endings, preventing successful parsing.","error":"Error: Malformed private key"},{"fix":"Use the correct ESM default import: `import githubAppJwt from 'universal-github-app-jwt';`. If you must use CommonJS, ensure you access the default export: `const githubAppJwt = require('universal-github-app-jwt').default;`.","cause":"This error typically occurs when attempting to import the `githubAppJwt` function using an incorrect import style, such as trying to destructure a default export (`import { githubAppJwt } from '...'`) or using `require()` without accessing `.default` in a CommonJS context.","error":"TypeError: githubAppJwt is not a function"},{"fix":"Ensure you are running in a modern browser with Web Crypto API support, a recent Node.js version (15.0.0+ for `crypto.subtle`), Deno, or Bun (>=2.2.1 for specific fixes). If in a browser, ensure it's not an older or highly restricted environment. No polyfills are officially supported by this library.","cause":"The JavaScript runtime environment (browser, Node.js, Deno, Bun) does not expose the `crypto.subtle` API, which is essential for the cryptographic operations performed by this library.","error":"ReferenceError: subtle is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/gr2m/universal-github-app-jwt","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/universal-github-app-jwt","openapi_spec":null,"status_page":null,"smithery":null,"categories":["auth-security","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}