| Browsers | ⚠️ `@octokit/auth-app` is not meant for usage in the browser. A private key and client secret must not be exposed to users. The private keys provided by GitHub are in `PKCS#1` format, but the WebCrypto API only supports `PKCS#8`. You need to convert it first: ```shell openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key ``` The OAuth APIs to create user-to-server tokens cannot be used because they do not have CORS enabled. If you know what you are doing, load `@octokit/auth-app` directly from [esm.sh](https://esm.sh) ```html ``` |
|---|---|
| Node |
Install with npm install @octokit/auth-app
```js
import { createAppAuth } from "@octokit/auth-app";
```
|
| Browsers | ⚠️ `@octokit/auth-app` is not meant for usage in the browser. A private key and client secret must not be exposed to users. The private keys provided by GitHub are in `PKCS#1` format, but the WebCrypto API only supports `PKCS#8`. You need to convert it first: ```shell openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key ``` The OAuth APIs to create user-to-server tokens cannot be used because they do not have CORS enabled. If you know what you are doing, load `@octokit/auth-app` and `@octokit/core` (or a compatible module) directly from [esm.sh](https://esm.sh) ```html ``` |
|---|---|
| Node | Install with `npm install @octokit/core @octokit/auth-app`. Optionally replace `@octokit/core` with a compatible module ```js import { Octokit } from "@octokit/core"; import { createAppAuth, createOAuthUserAuth } from "@octokit/auth-app"; ``` |
| name | type | description |
|---|---|---|
appId
|
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. If your private key contains escaped newlines (`\\n`), they will be automatically replaced with actual newlines.
|
installationId
|
number
|
Default installationId to be used when calling auth({ type: "installation" }).
|
clientId
|
string
|
The client ID of the GitHub App. |
clientSecret
|
string
|
A client secret for the GitHub App. |
request
|
function
|
Automatically set to `octokit.request` when using with an `Octokit` constructor. For standalone usage, you can pass in your own [`@octokit/request`](https://github.com/octokit/request.js) instance. For usage with enterprise, set `baseUrl` to the hostname + `/api/v3`. Example: ```js import { request } from "@octokit/request"; createAppAuth({ appId: 1, privateKey: "-----BEGIN PRIVATE KEY-----\n...", 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:
```js
const CACHE = {};
createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
cache: {
async get(key) {
return CACHE[key];
},
async set(key, value) {
CACHE[key] = value;
},
},
});
```
|
log
|
object
|
You can pass in your preferred logging tool by passing option.log to the constructor. If you would like to make the log level configurable using an environment variable or external option, we recommend the console-log-level package. For example:
```js
import consoleLogLevel from "console-log-level";
createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
log: consoleLogLevel({ level: "info" }),
});
```
|
| name | type | description |
|---|---|---|
type
|
string
|
Required. Must be either "app".
|
| name | type | description |
|---|---|---|
type
|
string
|
Required. Must be either "oauth-app".
|
| name | type | description |
|---|---|---|
type
|
string
|
Required. Must be "installation".
|
installationId
|
number
|
Required unless a default installationId was passed to createAppAuth(). ID of installation to retrieve authentication for.
|
repositoryIds
|
array of numbers
|
The id of the repositories that the installation token can access. Also known as a databaseID when querying the repository object in GitHub's GraphQL API. This option is **(recommended)** over repositoryNames when needing to limit the scope of the access token, due to repositoryNames having the possibility of changing. Additionally, you should only include either repositoryIds or repositoryNames, but not both.
|
repositoryNames
|
array of strings
|
The name of the repositories that the installation token can access. As mentioned in the repositoryIds description, you should only include either repositoryIds or repositoryNames, but not both.
|
permissions
|
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. |
factory
|
function
|
The `auth({type: "installation", installationId, factory })` call with resolve with whatever the factory function returns. The `factory` function will be called with all the strategy option that `auth` was created with, plus the additional options passed to `auth`, besides `type` and `factory`. For example, you can create a new `auth` instance for an installation which shares the internal state (especially the access token cache) with the calling `auth` instance: ```js const appAuth = createAppAuth({ appId: 1, privateKey: "-----BEGIN PRIVATE KEY-----\n...", }); const installationAuth123 = await appAuth({ type: "installation", installationId: 123, factory: createAppAuth, }); ``` |
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`. |
| name | type | description |
|---|---|---|
type
|
string
|
Required. Must be "oauth-user".
|
factory
|
function
|
The `auth({type: "oauth-user", factory })` call with resolve with whatever the factory function returns. The `factory` function will be called with all the strategy option that `auth` was created with, plus the additional options passed to `auth`, besides `type` and `factory`. For example, you can create a new `auth` instance for an installation which shares the internal state (especially the access token cache) with the calling `auth` instance: ```js import { createAppAuth, createOAuthUserAuth } from "@octokit/auth-oauth-app"; const appAuth = createAppAuth({ appId: 1, privateKey: "-----BEGIN PRIVATE KEY-----\n...", clientId: "lv1.1234567890abcdef", clientSecret: "1234567890abcdef1234567890abcdef12345678", }); const userAuth = await appAuth({ type: "oauth-user", code, factory: createOAuthUserAuth, }); // will create token upon first call, then cache authentication for successive calls, // until token needs to be refreshed (if enabled for the GitHub App) const authentication = await userAuth(); ``` |
code
|
string
|
The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow.
|
redirectUrl
|
string
|
The URL in your application where users are sent after authorization. See redirect urls. |
state
|
string
|
The unguessable random string you provided in Step 1 of the OAuth web application flow. |
| name | type | description |
|---|---|---|
type
|
string
|
Required. Must be "oauth-user".
|
onVerification
|
function
|
**Required**. A function that is called once the device and user codes were retrieved. The `onVerification()` callback can be used to pause until the user completes step 2, which might result in a better user experience. ```js const auth = auth({ type: "oauth-user", onVerification(verification) { console.log("Open %s", verification.verification_uri); console.log("Enter code: %s", verification.user_code); await prompt("press enter when you are ready to continue"); }, }); ``` |
factory
|
function
|
The `auth({type: "oauth-user", factory })` call with resolve with whatever the factory function returns. The `factory` function will be called with all the strategy option that `auth` was created with, plus the additional options passed to `auth`, besides `type` and `factory`. For example, you can create a new `auth` instance for an installation which shares the internal state (especially the access token cache) with the calling `auth` instance: ```js import { createAppAuth, createOAuthUserAuth } from "@octokit/auth-oauth-app"; const appAuth = createAppAuth({ appId: 1, privateKey: "-----BEGIN PRIVATE KEY-----\n...", clientId: "lv1.1234567890abcdef", clientSecret: "1234567890abcdef1234567890abcdef12345678", }); const userAuth = await appAuth({ type: "oauth-user", code, factory: createOAuthUserAuth, }); // will create token upon first call, then cache authentication for successive calls, // until token needs to be refreshed (if enabled for the GitHub App) const authentication = await userAuth(); ``` |
| name | type | description |
|---|---|---|
type
|
string
|
"app"
|
token
|
string
|
The JSON Web Token (JWT) to authenticate as the app. |
appId
|
number
|
GitHub App database ID. |
expiresAt
|
string
|
Timestamp in UTC format, e.g. "2018-07-07T00:09:30.000Z". A Date object can be created using new Date(authentication.expiresAt).
|
| name | type | description |
|---|---|---|
type
|
string
|
"oauth-app"
|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The client ID as passed to the constructor. |
clientSecret
|
string
|
The client secret as passed to the constructor. |
headers
|
object
|
{ authorization }.
|
| name | type | description |
|---|---|---|
type
|
string
|
"token"
|
token
|
string
|
The installation access token. |
tokenType
|
string
|
"installation"
|
installationId
|
number
|
Installation database ID. |
createdAt
|
string
|
Timestamp in UTC format, e.g. "2018-07-07T00:00:00.000Z". A Date object can be created using new Date(authentication.expiresAt).
|
expiresAt
|
string
|
Timestamp in UTC format, e.g. "2018-07-07T00:59:00.000Z". A Date object can be created using new Date(authentication.expiresAt).
|
repositoryIds
|
array of numbers
|
Only present if repositoryIds option passed to auth(options).
|
repositoryNames
|
array of strings
|
Only present if repositoryNames 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.
|
| name | type | description |
|---|---|---|
type
|
string
|
"token"
|
tokenType
|
string
|
"oauth"
|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
clientSecret
|
string
|
One of the app's client secrets |
token
|
string
|
The user access token |
| name | type | description |
|---|---|---|
type
|
string
|
"token"
|
tokenType
|
string
|
"oauth"
|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
clientSecret
|
string
|
One of the app's client secrets |
token
|
string
|
The user access token |
refreshToken
|
string
|
The refresh token |
expiresAt
|
string
|
Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
|
refreshTokenExpiresAt
|
string
|
Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z
|