Reference

OAuth2Client.createAuthorizationURL()

Creates an authorization URL. The scope query parameter will not be set if scopes parameter is a empty array.

OAuth2Client.createAuthorizationURLWithPKCE()

Creates an authorization URL for PKCE flow. The scope query parameter will not be set if scopes parameter is a empty array.

Definition

function createAuthorizationURLWithPKCE(
    authorizationEndpoint: string,
    state: string,
    codeChallengeMethod: CodeChallengeMethod,
    codeVerifier: string,
    scopes: string[]
);

Parameters

authorizationEndpoint
state
codeChallengeMethod
codeVerifier
scopes

OAuth2Client.validateAuthorizationCode()

Validates an authorization code for an access token. Pass codeVerifier for PKCE.

OAuth2Client.refreshAccessToken()

Refreshes an access token with a refresh token. The scope request parameter will not be set if scopes parameter is a empty array.

OAuth2Tokens.accessToken()

Returns the access_token field value. Throws an Error if the field is missing or the value isn't a string.

Definition

function accessToken(): string;

OAuth2Tokens.accessTokenExpiresAt()

Gets the expires_in field value and returns the expiration Date. Throws an Error if the field is missing or the value isn't a number.

Definition

function accessTokenExpiresAt(): Date;

OAuth2Tokens.accessTokenExpiresInSeconds()

Returns the expires_in field value. Throws an Error if the field is missing or the value isn't a number.

Definition

function accessTokenExpiresInSeconds(): number;

OAuth2Tokens.hasRefreshToken()

Returns refresh_token if the error field exists and the value is a string.

Definition

function hasRefreshToken(): boolean;

OAuth2Tokens.refreshToken()

Returns the refresh_token field value. Throws an Error if the field is missing or the value isn't a string.

Definition

function refreshToken(): string;

OAuth2Tokens.idToken()

Returns the id_token field value. Throws an Error if the field is missing or the value isn't a string.

Definition

function idToken(): string;

CodeChallengeMethod

Definition

enum CodeChallengeMethod {
    S256,
    Plain
}

generateCodeVerifier()

Generates a cryptographically secure random code verifier with the Web Crypto API.

Definition

function generateCodeVerifier(): string;

generateState()

Generates a cryptographically secure random state with the Web Crypto API.

Definition

function generateState(): string;

ArcticFetchError

Extends Error.

Error indicating that the fetch() call failed. See ArcticFetchError.cause for the error thrown by fetch().

OAuth2RequestError

Extends Error.

Error indicating that the provider returned an OAuth 2.0 error response.

Properties

interface Properties {
    code: string;
    description: string | null;
    uri: string | null;
    state: string | null;
}

code: The error field
description: The error_description field
uri: The error_uri field
state: The state field

UnexpectedErrorResponseBodyError

Extends Error.

Indicates an unexpected error response JSON body.

Properties

interface Properties {
    status: number;
    data: unknown;
}

status: Response body status.
data: JSON.parse()-ed response body.

ProviderOptions

The object form of every provider constructor.

interface ProviderOptions {
    clientId?: string;
    clientSecret?: string;
    redirectURI?: string;
    scopes?: string[];
    store: Store;
}

store is any polystore compatible key-value store. Everything else falls back to the environment and then to the provider default. Providers that need extra values, such as Auth0's domain, add them to their own options interface.

OAuthUser

The normalized profile returned by getUser().

interface OAuthUser {
    id: string;
    name?: string | null;
    email?: string | null;
    image?: string | null;
    raw?: Record<string, unknown>;
    accessToken?: string;
    refreshToken?: string | null;
    scopes?: string[] | null;
}

Fields the provider does not expose are null.

raw is the provider's own payload, so you can read fields the normalized shape does not model. It is the profile response for providers with a user endpoint, and the decoded ID token claims for OIDC providers.

accessToken lets you call the provider's API as the user. refreshToken and scopes are null when the provider did not return them.

AuthorizationRequest

What getAuthorizationURL() returns.

interface AuthorizationRequest {
    url: URL;
    state: string;
    payload: StoredOAuthState;
}

payload holds the PKCE verifier where the provider uses one, and is empty otherwise. Both state and payload are written to the store, and can be passed back to getUser() as { state, payload } to skip it.

const error: OAuthProviderError;
error.code; // string | null, the provider's error code when it sent one

Secrets, tokens, and PKCE verifiers are never included in any of these messages.