Client

Reference doc for the OpenAuth client.

Use the OpenAuth client kick off your OAuth flows, exchange tokens, refresh tokens, and verify tokens.

First, create a client.

import { createClient } from "@openauthjs/openauth/client"

const client = createClient({
  clientID: "my-client",
  issuer: "https://auth.myserver.com"
})

Kick off the OAuth flow by calling authorize.

const redirect_uri = "https://myserver.com/callback"

const { url } = await client.authorize(
  redirect_uri,
  "code"
)

When the user completes the flow, exchange the code for tokens.

const tokens = await client.exchange(query.get("code"), redirect_uri)

And verify the tokens.

const verified = await client.verify(subjects, tokens.access)

Methods

createClient

createClient(input)

Parameters

input ClientInput
Configure the client.

Returns Client

Create an OpenAuth client.

Client

An instance of the OpenAuth client contains the following methods.

authorize

Type (redirectURI: string, response: “code” | “token”, opts?: AuthorizeOptions) => Promise<AuthorizeResult>

Start the autorization flow. For example, in SSR sites.

const { url } = await client.authorize(<redirect_uri>, "code")

This takes a redirect URI and the type of flow you want to use. The redirect URI is the location where the user will be redirected to after the flow is complete.

Supports both the code and token flows. We recommend using the code flow as it’s more secure.

This returns a URL to the auth server. You can redirect the user to the URL to start the OAuth flow.

For SPA apps, we recommend using the PKCE flow.

const { challenge, url } = await client.authorize(
  <redirect_uri>,
  "code",
  { pkce: true }
)

This returns a redirect URL and a challenge that you need to use later to verify the code.

exchange

Type (code: string, redirectURI: string, verifier?: string) => Promise<ExchangeSuccess | ExchangeError>

Exchange the code for access and refresh tokens.

const exchanged = await client.exchange(<code>, <redirect_uri>)

You call this after the user has been redirected back to your app after the OAuth flow.

So the code comes from the query parameter in the redirect URI. The redirect URI here is the one that you passed in to the authorize call when starting the flow.

If you used the PKCE flow for an SPA app, the code is returned as a part of the redirect URL hash.

const exchanged = await client.exchange(
  <code>,
  <redirect_uri>,
  <challenge.verifier>
)

You also need to pass in the previously stored challenge verifier.

This method returns the access and refresh tokens. Or if it fails, it returns an error that you can handle depending on the error.

import { InvalidAuthorizationCodeError } from "@openauthjs/openauth/error"

if (exchanged.err) {
  if (exchanged.err instanceof InvalidAuthorizationCodeError) {
    // handle invalid code error
  }
  else {
    // handle other errors
  }
}

const { access, refresh } = exchanged.tokens

refresh

Type (refresh: string, opts?: RefreshOptions) => Promise<RefreshSuccess | RefreshError>

Refreshes the tokens if they have expired. This is used in an SPA app to maintain the session, without logging the user out.

const next = await client.refresh(<refresh_token>)

Can optionally take the access token as well. If passed in, this will skip the refresh if the access token is still valid.

const next = await client.refresh(<refresh_token>, { access: <access_token> })

This returns the refreshed tokens only if they’ve been refreshed.

if (!next.err) {
  // tokens are still valid
}
if (next.tokens) {
  const { access, refresh } = next.tokens
}

Or if it fails, it returns an error that you can handle depending on the error.

import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"

if (next.err) {
  if (next.err instanceof InvalidRefreshTokenError) {
    // handle invalid refresh token error
  }
  else {
    // handle other errors
  }
}

verify

Type (subjects: SubjectSchema, token: string, options?: VerifyOptions) => Promise<VerifyError | VerifyResult>

Verify the token in the incoming request.

This is typically used for SSR sites where the token is stored in an HTTP only cookie. And is passed to the server on every request.

const verified = await client.verify(<subjects>, <token>)

This takes the subjects that you had previously defined when creating the issuer.

This can optionally take the refresh token as well. If passed in, it’ll automatically refresh the access token if it has expired.

const verified = await client.verify(<subjects>, <token>, { refresh: <refresh_token> })

This returns the decoded subjects from the access token. And the tokens if they’ve been refreshed.

// based on the subjects you defined earlier
console.log(verified.subject.properties.userID)

if (verified.tokens) {
  const { access, refresh } = verified.tokens
}

Or if it fails, it returns an error that you can handle depending on the error.

import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"

if (verified.err) {
  if (verified.err instanceof InvalidRefreshTokenError) {
    // handle invalid refresh token error
  }
  else {
    // handle other errors
  }
}

AuthorizeOptions

pkce? boolean
provider? string

AuthorizeOptions.pkce?

Type boolean

Default false

Enable the PKCE flow. This is for SPA apps.

{
  pkce: true
}

AuthorizeOptions.provider?

Type string

The provider you want to use for the OAuth flow.

{
  provider: "google"
}

If no provider is specified, the user is directed to a page where they can select from the list of configured providers.

If there’s only one provider configured, the user will be redirected to that.

AuthorizeResult

challenge Challenge
url string

AuthorizeResult.challenge

Type Challenge

The challenge that you can use to verify the code. This is for the PKCE flow for SPA apps.

This is an object that you stringify and store it in session storage.

sessionStorage.setItem("challenge", JSON.stringify(challenge))

AuthorizeResult.url

Type string

The URL to redirect the user to. This starts the OAuth flow.

For example, for SPA apps.

location.href = url

Challenge

Type Object

The challenge that you can use to verify the code.

ClientInput

clientID string
fetch? FetchLike
issuer? string

Configure the client.

ClientInput.clientID

Type string

The client ID. This is just a string to identify your app.

If you have a web app and a mobile app, you want to use different client IDs both.

{
  clientID: "my-client"
}

ClientInput.fetch?

Type FetchLike

Optionally, override the internally used fetch function.

This is useful if you are using a polyfilled fetch function in your application and you want the client to use it too.

ClientInput.issuer?

Type string

The URL of your OpenAuth server.

{
  issuer: "https://auth.myserver.com"
}

ExchangeError

err InvalidAuthorizationCodeError

Returned when the exchange fails.

ExchangeError.err

Type InvalidAuthorizationCodeError

The type of error that occurred. You can handle this by checking the type.

import { InvalidAuthorizationCodeError } from "@openauthjs/openauth/error"

console.log(err instanceof InvalidAuthorizationCodeError)

ExchangeSuccess

err false
tokens Tokens

Returned when the exchange is successful.

err InvalidRefreshTokenError | InvalidAccessTokenError

Returned when the refresh fails.

RefreshError.err

Type InvalidRefreshTokenError | InvalidAccessTokenError

The type of error that occurred. You can handle this by checking the type.

import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"

console.log(err instanceof InvalidRefreshTokenError)

RefreshOptions

access? string

RefreshOptions.access?

Type string

Optionally, pass in the access token.

RefreshSuccess

err false
tokens? Tokens

Returned when the refresh is successful.

RefreshSuccess.err

Type false

This is always false when the refresh is successful.

RefreshSuccess.tokens?

Type Tokens

Returns the refreshed tokens only if they’ve been refreshed.

If they are still valid, this will be undefined.

Tokens

access string
refresh string

The tokens returned by the auth server.

err InvalidRefreshTokenError | InvalidAccessTokenError

Returned when the verify call fails.

VerifyError.err

Type InvalidRefreshTokenError | InvalidAccessTokenError

The type of error that occurred. You can handle this by checking the type.

import { InvalidRefreshTokenError } from "@openauthjs/openauth/error"

console.log(err instanceof InvalidRefreshTokenError)

VerifyOptions

fetch? FetchLike
refresh? string

VerifyOptions.fetch?

Type FetchLike

Optionally, override the internally used fetch function.

This is useful if you are using a polyfilled fetch function in your application and you want the client to use it too.

VerifyOptions.refresh?

Type string

Optionally, pass in the refresh token.

If passed in, this will automatically refresh the access token if it has expired.

VerifyResult

err? undefined
subject Subject
tokens? Tokens

VerifyResult.err?

Type undefined

This is always undefined when the verify is successful.

VerifyResult.subject

Type Subject

The decoded subjects from the access token.

Has the same shape as the subjects you defined when creating the issuer.

VerifyResult.tokens?

Type Tokens

Returns the refreshed tokens only if they’ve been refreshed.

If they are still valid, this will be undefined.