https://github.com/octokit/oauth-authorization-url.js
Universal library to retrieve GitHub’s identity URL for the OAuth web flow
https://github.com/octokit/oauth-authorization-url.js
hacktoberfest oauth octokit-js plugin
Last synced: 7 months ago
JSON representation
Universal library to retrieve GitHub’s identity URL for the OAuth web flow
- Host: GitHub
- URL: https://github.com/octokit/oauth-authorization-url.js
- Owner: octokit
- License: mit
- Created: 2019-04-05T21:11:06.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-05-20T06:09:00.000Z (8 months ago)
- Last Synced: 2025-05-20T06:11:14.466Z (8 months ago)
- Topics: hacktoberfest, oauth, octokit-js, plugin
- Language: TypeScript
- Homepage:
- Size: 2.5 MB
- Stars: 18
- Watchers: 7
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# oauth-authorization-url.js
> Universal library to retrieve GitHub’s identity URL for the OAuth web flow
[](https://www.npmjs.com/package/@octokit/oauth-authorization-url)
[](https://github.com/octokit/oauth-authorization-url.js/actions?query=workflow%3ATest+branch%3Amain)
See [GitHub’s Developer Guide for the OAuth App web application flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). Note that the [OAuth web application flow for GitHub Apps](https://docs.github.com/en/developers/apps/identifying-and-authorizing-users-for-github-apps#web-application-flow) is slightly different. GitHub Apps do not support scopes for its user access tokens (they are called user-to-server tokens for GitHub Apps), instead they inherit the user permissions from the GitHub App's registration and the repository/organization access and permissions from the respective installation.
- [Usage](#usage)
- [For OAuth Apps](#for-oauth-apps)
- [For GitHub Apps](#for-github-apps)
- [Options](#options)
- [Result](#result)
- [Types](#types)
- [License](#license)
## Usage
Browsers
Load `@octokit/oauth-authorization-url` directly from [esm.sh](https://esm.sh)
```html
import { oauthAuthorizationUrl } from "https://esm.sh/@octokit/oauth-authorization-url";
```
Node
Install with npm install @octokit/oauth-authorization-url
```js
const { oauthAuthorizationUrl } = require("@octokit/oauth-authorization-url");
// or: import { oauthAuthorizationUrl } from "@octokit/oauth-authorization-url";
```
> [!IMPORTANT]
> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
>
> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).
> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/sindresorhus)
### For OAuth Apps
```js
const { url, clientId, redirectUrl, login, scopes, state } =
oauthAuthorizationUrl({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
redirectUrl: "https://example.com",
login: "octocat",
scopes: ["repo", "admin:org"],
state: "secret123",
});
```
### For GitHub Apps
```js
const { url, clientId, redirectUrl, login, state } = oauthAuthorizationUrl({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
redirectUrl: "https://example.com",
login: "octocat",
state: "secret123",
});
```
## Options
name
description
clientId
Required. The client ID you received from GitHub when you registered.
clientType
Must be set to either `"oauth-app"` or `"github-app"`. Defaults to `"oauth-app"`.
redirectUrl
The URL in your application where users will be sent after authorization. See Redirect URLs in GitHub’s Developer Guide.
login
Suggests a specific account to use for signing in and authorizing the app.
scopes
Only relevant when `clientType` is set to `"oauth-app"`.
An array of scope names (or: space-delimited list of scopes). If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
Defaults to `[]` if `clientType` is set to `"oauth-app"`.
state
An unguessable random string. It is used to protect against cross-site request forgery attacks.
Defaults to Math.random().toString(36).substr(2).
allowSignup
Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. Use false in the case that a policy prohibits signups. Defaults to true.
baseUrl
When using GitHub Enterprise Server, set the baseUrl to the origin, e.g. https://github.my-enterprise.com.
## Result
`oauthAuthorizationUrl()` returns an object with the following properties
name
description
allowSignup
Returns options.allowSignup if it was set. Defaults to true.
clientType
Returns options.clientType. Defaults to "oauth-app".
clientId
Returns options.clientId.
login
Returns options.login if it was set. Defaults to null.
redirectUrl
Returns options.redirectUrl if it was set. Defaults to null.
scopes
Only set if `options.clientType` is set to `"oauth-app"`.
Returns an array of strings. Returns options.scopes if it was set and turns the string into an array if a string was passed, otherwise [].
state
Returns options.state if it was set. Defaults to Defaults to Math.random().toString(36).substr(2).
url
The authorization URL
## Types
```ts
import {
ClientType,
OAuthAppOptions,
OAuthAppResult,
GitHubAppOptions,
GitHubAppResult,
} from "@octokit/oauth-authorization-url";
```
## License
[MIT](LICENSE)