1.3.1.3 Auth OAuth App

"GitHub OAuth App authentication for JavaScript: implements one of GitHub’s authentication strategies."

• octokit/auth-oauth-app

It implements authentication using an OAuth app’s

• client ID and secret as well as
• OAuth access tokens in exchange for
• a code from the web application flow.

Load @octokit/auth-oauth-app directly from cdn.skypack.dev

<script type="module"> import { createOAuthAppAuth } from "https://cdn.skypack.dev/@octokit/auth-oauth-app"; </script>

In Node.js, install with

npm install @octokit/auth-oauth-app
const { createOAuthAppAuth } = require("@octokit/auth-oauth-app");
// or:
import { createOAuthAppAuth } from "@octokit/auth-oauth-app";

‘Client ID’ and ‘secret’ can be passed as ‘Basic auth’ in the ‘Authorization’ header in order to get a higher rate limit compared to unauthenticated requests. This is meant for the use on servers only.

1. Create OAuth App Auth Method

   The createOAuthAppAuth(options) method accepts a single ‘options’ parameter with the following possible keys:

   clientId

   (string) Required Find your OAuth app’s Client ID in your account’s developer settings.

   clientSectret

   (string) Required Find your OAuth app’s Client Secret in your account’s developer settings.

   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.

   requrest

   (function) You can pass in your own @octokit/request instance.

2. Auth Method

   The async auth(options) method returned by createOAuthAppAuth(options) accepts the following options:

   type

   (string) Required "oauth-app" or "token"

   code

   (string) Only relevant if ‘options.type’ is set to "token". The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow. Defaults to what was set in the strategy options.

   redirectUrl

   (string) Only relevant if ‘options.type’ is set to "token". The URL in your application where users are sent after authorization. See redirect urls. Defaults to what was set in the strategy options.

   state

   (string) Only relevant if ‘options.type’ is set to "token". The unguessable random string you provided in Step 1 of the OAuth web application flow. Defaults to what was set in the strategy options.

3. Authentication Object

   The async auth(options) method returns one of two possible authentication objects.

   1. ‘OAuth authentication’ if ‘clientId’ and ‘clientSecret’ options were passed.
   2. ‘OAuth access token authentication’ if ‘code’ option was passed.
   1. OAuth Authentication

      type

      (string) "oauth-app"

      clientId

      (string) The client ID as passed to the constructor.

      clientSecret

      (string) The client secret as passed to the constructor.

      headers

      (object) ‘{ authorization }’

   2. OAuth access token authentication

      type

      (string) "token"

      token

      (string) The personal access token

      tokenType

      (string) "oauth"

      scopes

      ([strings]) array of scope names enabled for the token

4. Auth Hook
   • auth.hook(request, route, parameters)
   • auth.hook(request, options)

   auth.hook() hooks directly into the ‘request’ life cycle. It amends the ‘request’ to authenticate correctly based on the ‘request’ URL.

   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: user } = await auth.hook(request, "GET /user");
   

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

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

   auth.hook will set the correct ‘Authentication’ header automatically based on the ‘request’ URL.

   • For all OAuth Application endpoints, the ‘Authorization’ header is set to ‘basic’ auth.
   • For all other endpoints a token is retrieved and used in the ‘Authorization’ header. The token is cached and used for succeeding requsets.
   • The internally cached token will be replaced and used for succeeding requests. See also "the REST API documentation".
   • See also: octokit/oauth-authorization-url.js.