Auth

This is the main module to interact with Nhost’s Auth service. Typically you would use this module via the main Nhost client but you can also use it directly if you have a specific use case.

Import

You can import and use this package with:

import { createClient } from '@nhost/nhost-js/auth'

Usage

import { createClient } from '@nhost/nhost-js'

const nhost = createClient({
  subdomain,
  region
})

await nhost.auth.signUpEmailPassword({
  email,
  password
})

Error handling

The SDK will throw errors in most operations if the request returns a status >=300 or if the request fails entirely (i.e., due to network errors). The type of the error will be a FetchError<ErrorResponse>:

import { createClient } from '@nhost/nhost-js'
import { FetchError } from '@nhost/nhost-js/fetch'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.auth.signInEmailPassword({
    email,
    password
  })
} catch (err) {
  if (!(err instanceof FetchError)) {
    throw err // Re-throw if it's not a FetchError
  }

  console.log('Error:', err)
  // Error: {
  //   body: {
  //     error: 'invalid-email-password',
  //     message: 'Incorrect email or password',
  //     status: 401
  //   },
  //   status: 401,
  //   headers: {
  //     'content-length': '88',
  //     'content-type': 'application/json',
  //     date: 'Mon, 12 May 2025 08:08:28 GMT'
  //   }
  // }

  // error handling...
}

This type extends the standard Error type so if you want to just log the error you can do so like this:

import { createClient } from '@nhost/nhost-js'
import { FetchError } from '@nhost/nhost-js/fetch'

const nhost = createClient({
  subdomain,
  region
})

try {
  await nhost.auth.signInEmailPassword({
    email,
    password
  })
} catch (err) {
  if (!(err instanceof Error)) {
    throw err // Re-throw if it's not an Error
  }

  console.log('Error:', err.message)
  // Error: Incorrect email or password
}

Interfaces

AuthenticationExtensionsClientOutputs

Map of extension outputs from the client

Properties

appid?

optional appid: boolean;

Application identifier extension output

credProps?

optional credProps: CredentialPropertiesOutput;

Credential properties extension output

hmacCreateSecret?

optional hmacCreateSecret: boolean;

HMAC secret extension output

---

AuthenticatorAssertionResponse

Properties

authenticatorData

authenticatorData: string

(string) - Base64url encoded authenticator data

clientDataJSON

clientDataJSON: string

(string) - Base64url encoded client data JSON

signature

signature: string

(string) - Base64url encoded assertion signature

userHandle?

optional userHandle: string;

Base64url encoded user handle

---

AuthenticatorAttestationResponse

Properties

attestationObject

attestationObject: string

(string) - Base64url-encoded binary data

• Format - byte

authenticatorData?

optional authenticatorData: string;

Base64url-encoded binary data Format - byte

clientDataJSON

clientDataJSON: string

(string) - Base64url-encoded binary data

• Format - byte

publicKey?

optional publicKey: string;

Base64url-encoded binary data Format - byte

publicKeyAlgorithm?

optional publicKeyAlgorithm: number;

The public key algorithm identifier Format - int64

transports?

optional transports: string[];

The authenticator transports

---

AuthenticatorSelection

Properties

authenticatorAttachment?

optional authenticatorAttachment: AuthenticatorAttachment;

The authenticator attachment modality

requireResidentKey?

optional requireResidentKey: boolean;

Whether the authenticator must create a client-side-resident public key credential source

residentKey?

optional residentKey: ResidentKeyRequirement;

The resident key requirement

userVerification?

optional userVerification: UserVerificationRequirement;

A requirement for user verification for the operation

---

Client

Properties

baseURL

baseURL: string

Methods

addSecurityKey()

addSecurityKey(options?: RequestInit): Promise<FetchResponse<PublicKeyCredentialCreationOptions>>;

Summary: Initialize adding of a new webauthn security key Start the process of adding a new WebAuthn security key to the user’s account. Returns a challenge that must be completed by the user’s authenticator device. Requires elevated permissions.

This method may return different T based on the response code:

• 200: PublicKeyCredentialCreationOptions

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<PublicKeyCredentialCreationOptions>>

changeUserEmail()

changeUserEmail(body: UserEmailChangeRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Change user email Request to change the authenticated user’s email address. A verification email will be sent to the new address to confirm the change. Requires elevated permissions.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserEmailChangeRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

changeUserMfa()

changeUserMfa(options?: RequestInit): Promise<FetchResponse<TotpGenerateResponse>>;

Summary: Generate TOTP secret Generate a Time-based One-Time Password (TOTP) secret for setting up multi-factor authentication

This method may return different T based on the response code:

• 200: TotpGenerateResponse

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<TotpGenerateResponse>>

changeUserPassword()

changeUserPassword(body: UserPasswordRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Change user password Change the user’s password. The user must be authenticated with elevated permissions or provide a valid password reset ticket.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserPasswordRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

createPAT()

createPAT(body: CreatePATRequest, options?: RequestInit): Promise<FetchResponse<CreatePATResponse>>;

Summary: Create a Personal Access Token (PAT) Generate a new Personal Access Token for programmatic API access. PATs are long-lived tokens that can be used instead of regular authentication for automated systems. Requires elevated permissions.

This method may return different T based on the response code:

• 200: CreatePATResponse

Parameters

Parameter	Type
body	CreatePATRequest
options?	RequestInit

Returns

Promise<FetchResponse<CreatePATResponse>>

deanonymizeUser()

deanonymizeUser(body: UserDeanonymizeRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Deanonymize an anonymous user Convert an anonymous user to a regular user by adding email and optionally password credentials. A confirmation email will be sent if the server is configured to do so.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserDeanonymizeRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

elevateWebauthn()

elevateWebauthn(options?: RequestInit): Promise<FetchResponse<PublicKeyCredentialRequestOptions>>;

Summary: Elevate access for an already signed in user using FIDO2 Webauthn Generate a Webauthn challenge for elevating user permissions

This method may return different T based on the response code:

• 200: PublicKeyCredentialRequestOptions

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<PublicKeyCredentialRequestOptions>>

getJWKs()

getJWKs(options?: RequestInit): Promise<FetchResponse<JWKSet>>;

Summary: Get public keys for JWT verification in JWK Set format Retrieve the JSON Web Key Set (JWKS) containing public keys used to verify JWT signatures. This endpoint is used by clients to validate access tokens.

This method may return different T based on the response code:

• 200: JWKSet

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<JWKSet>>

getProviderTokens()

getProviderTokens(provider: SignInProvider, options?: RequestInit): Promise<FetchResponse<ProviderSession>>;

Summary: Retrieve OAuth2 provider tokens from callback After successful OAuth2 authentication, retrieve the provider session containing access token, refresh token, and expiration information for the specified provider. To ensure the data isn’t stale this endpoint must be called immediately after the OAuth callback to obtain the tokens. The session is cleared from the database during this call, so subsequent calls will fail without going through the sign-in flow again. It is the user’s responsibility to store the session safely (e.g., in browser local storage).

This method may return different T based on the response code:

• 200: ProviderSession

Parameters

Parameter	Type
provider	SignInProvider
options?	RequestInit

Returns

Promise<FetchResponse<ProviderSession>>

getUser()

getUser(options?: RequestInit): Promise<FetchResponse<User>>;

Summary: Get user information Retrieve the authenticated user’s profile information including roles, metadata, and account status.

This method may return different T based on the response code:

• 200: User

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<User>>

getVersion()

getVersion(options?: RequestInit): Promise<FetchResponse<GetVersionResponse200>>;

Summary: Get service version Retrieve version information about the authentication service

This method may return different T based on the response code:

• 200: GetVersionResponse200

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<GetVersionResponse200>>

healthCheckGet()

healthCheckGet(options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Health check (GET) Verify if the authentication service is operational using GET method

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

healthCheckHead()

healthCheckHead(options?: RequestInit): Promise<FetchResponse<void>>;

Summary: Health check (HEAD) Verify if the authentication service is operational using HEAD method

This method may return different T based on the response code:

• 200: void

Parameters

Parameter	Type
options?	RequestInit

Returns

Promise<FetchResponse<void>>

linkIdToken()

linkIdToken(body: LinkIdTokenRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Link a user account with the provider’s account using an id token Link the authenticated user’s account with an external OAuth provider account using an ID token. Requires elevated permissions.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	LinkIdTokenRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

pushChainFunction()

pushChainFunction(chainFunction: ChainFunction): void;

Add a middleware function to the fetch chain

Parameters

Parameter	Type	Description
chainFunction	ChainFunction	The middleware function to add

Returns

void

refreshProviderToken()

refreshProviderToken(
   provider: SignInProvider,
   body: RefreshProviderTokenRequest,
   options?: RequestInit): Promise<FetchResponse<ProviderSession>>;

Summary: Refresh OAuth2 provider tokens Refresh the OAuth2 provider access token using a valid refresh token. Returns a new provider session with updated access token, refresh token (if rotated by provider), and expiration information. This endpoint allows maintaining long-lived access to provider APIs without requiring the user to re-authenticate.

This method may return different T based on the response code:

• 200: ProviderSession

Parameters

Parameter	Type
provider	SignInProvider
body	RefreshProviderTokenRequest
options?	RequestInit

Returns

Promise<FetchResponse<ProviderSession>>

refreshToken()

refreshToken(body: RefreshTokenRequest, options?: RequestInit): Promise<FetchResponse<Session>>;

Summary: Refresh access token Generate a new JWT access token using a valid refresh token. The refresh token used will be revoked and a new one will be issued.

This method may return different T based on the response code:

• 200: Session

Parameters

Parameter	Type
body	RefreshTokenRequest
options?	RequestInit

Returns

Promise<FetchResponse<Session>>

sendPasswordResetEmail()

sendPasswordResetEmail(body: UserPasswordResetRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Request password reset Request a password reset for a user account. An email with a verification link will be sent to the user’s email address to complete the password reset process.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserPasswordResetRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

sendVerificationEmail()

sendVerificationEmail(body: UserEmailSendVerificationEmailRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Send verification email Send an email verification link to the specified email address. Used to verify email addresses for new accounts or email changes.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserEmailSendVerificationEmailRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

signInAnonymous()

signInAnonymous(body?: SignInAnonymousRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Sign in anonymously Create an anonymous user session without providing credentials. Anonymous users can be converted to regular users later via the deanonymize endpoint.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body?	SignInAnonymousRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

signInEmailPassword()

signInEmailPassword(body: SignInEmailPasswordRequest, options?: RequestInit): Promise<FetchResponse<SignInEmailPasswordResponse>>;

Summary: Sign in with email and password Authenticate a user with their email and password. Returns a session object or MFA challenge if two-factor authentication is enabled.

This method may return different T based on the response code:

• 200: SignInEmailPasswordResponse

Parameters

Parameter	Type
body	SignInEmailPasswordRequest
options?	RequestInit

Returns

Promise<FetchResponse<SignInEmailPasswordResponse>>

signInIdToken()

signInIdToken(body: SignInIdTokenRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Sign in with an ID token Authenticate using an ID token from a supported OAuth provider (Apple or Google). Creates a new user account if one doesn’t exist.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignInIdTokenRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

signInOTPEmail()

signInOTPEmail(body: SignInOTPEmailRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Sign in with email OTP Initiate email-based one-time password authentication. Sends an OTP to the specified email address. If the user doesn’t exist, a new account will be created with the provided options.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	SignInOTPEmailRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

signInPasswordlessEmail()

signInPasswordlessEmail(body: SignInPasswordlessEmailRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Sign in with magic link email Initiate passwordless authentication by sending a magic link to the user’s email. If the user doesn’t exist, a new account will be created with the provided options.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	SignInPasswordlessEmailRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

signInPasswordlessSms()

signInPasswordlessSms(body: SignInPasswordlessSmsRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Sign in with SMS OTP Initiate passwordless authentication by sending a one-time password to the user’s phone number. If the user doesn’t exist, a new account will be created with the provided options.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	SignInPasswordlessSmsRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

signInPAT()

signInPAT(body: SignInPATRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Sign in with Personal Access Token (PAT) Authenticate using a Personal Access Token. PATs are long-lived tokens that can be used for programmatic access to the API.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignInPATRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

signInProviderURL()

signInProviderURL(
   provider: SignInProvider,
   params?: SignInProviderParams,
   options?: RequestInit): string;

Summary: Sign in with an OAuth2 provider Initiate OAuth2 authentication flow with a social provider. Redirects the user to the provider’s authorization page.

As this method is a redirect, it returns a URL string instead of a Promise

Parameters

Parameter	Type
provider	SignInProvider
params?	SignInProviderParams
options?	RequestInit

Returns

string

signInWebauthn()

signInWebauthn(body?: SignInWebauthnRequest, options?: RequestInit): Promise<FetchResponse<PublicKeyCredentialRequestOptions>>;

Summary: Sign in with Webauthn Initiate a Webauthn sign-in process by sending a challenge to the user’s device. The user must have previously registered a Webauthn credential.

This method may return different T based on the response code:

• 200: PublicKeyCredentialRequestOptions

Parameters

Parameter	Type
body?	SignInWebauthnRequest
options?	RequestInit

Returns

Promise<FetchResponse<PublicKeyCredentialRequestOptions>>

signOut()

signOut(body: SignOutRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Sign out End the current user session by invalidating refresh tokens. Optionally sign out from all devices.

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	SignOutRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

signUpEmailPassword()

signUpEmailPassword(body: SignUpEmailPasswordRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Sign up with email and password Register a new user account with email and password. Returns a session if email verification is not required, otherwise returns null session.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignUpEmailPasswordRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

signUpWebauthn()

signUpWebauthn(body: SignUpWebauthnRequest, options?: RequestInit): Promise<FetchResponse<PublicKeyCredentialCreationOptions>>;

Summary: Sign up with Webauthn Initiate a Webauthn sign-up process by sending a challenge to the user’s device. The user must not have an existing account.

This method may return different T based on the response code:

• 200: PublicKeyCredentialCreationOptions

Parameters

Parameter	Type
body	SignUpWebauthnRequest
options?	RequestInit

Returns

Promise<FetchResponse<PublicKeyCredentialCreationOptions>>

verifyAddSecurityKey()

verifyAddSecurityKey(body: VerifyAddSecurityKeyRequest, options?: RequestInit): Promise<FetchResponse<VerifyAddSecurityKeyResponse>>;

Summary: Verify adding of a new webauthn security key Complete the process of adding a new WebAuthn security key by verifying the authenticator response. Requires elevated permissions.

This method may return different T based on the response code:

• 200: VerifyAddSecurityKeyResponse

Parameters

Parameter	Type
body	VerifyAddSecurityKeyRequest
options?	RequestInit

Returns

Promise<FetchResponse<VerifyAddSecurityKeyResponse>>

verifyChangeUserMfa()

verifyChangeUserMfa(body: UserMfaRequest, options?: RequestInit): Promise<FetchResponse<"OK">>;

Summary: Manage multi-factor authentication Activate or deactivate multi-factor authentication for the authenticated user

This method may return different T based on the response code:

• 200: OKResponse

Parameters

Parameter	Type
body	UserMfaRequest
options?	RequestInit

Returns

Promise<FetchResponse<"OK">>

verifyElevateWebauthn()

verifyElevateWebauthn(body: SignInWebauthnVerifyRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Verify FIDO2 Webauthn authentication using public-key cryptography for elevation Complete Webauthn elevation by verifying the authentication response

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignInWebauthnVerifyRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

verifySignInMfaTotp()

verifySignInMfaTotp(body: SignInMfaTotpRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Verify TOTP for MFA Complete the multi-factor authentication by verifying a Time-based One-Time Password (TOTP). Returns a session if validation is successful.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignInMfaTotpRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

verifySignInOTPEmail()

verifySignInOTPEmail(body: SignInOTPEmailVerifyRequest, options?: RequestInit): Promise<FetchResponse<SignInOTPEmailVerifyResponse>>;

Summary: Verify email OTP Complete email OTP authentication by verifying the one-time password. Returns a session if validation is successful.

This method may return different T based on the response code:

• 200: SignInOTPEmailVerifyResponse

Parameters

Parameter	Type
body	SignInOTPEmailVerifyRequest
options?	RequestInit

Returns

Promise<FetchResponse<SignInOTPEmailVerifyResponse>>

verifySignInPasswordlessSms()

verifySignInPasswordlessSms(body: SignInPasswordlessSmsOtpRequest, options?: RequestInit): Promise<FetchResponse<SignInPasswordlessSmsOtpResponse>>;

Summary: Verify SMS OTP Complete passwordless SMS authentication by verifying the one-time password. Returns a session if validation is successful.

This method may return different T based on the response code:

• 200: SignInPasswordlessSmsOtpResponse

Parameters

Parameter	Type
body	SignInPasswordlessSmsOtpRequest
options?	RequestInit

Returns

Promise<FetchResponse<SignInPasswordlessSmsOtpResponse>>

verifySignInWebauthn()

verifySignInWebauthn(body: SignInWebauthnVerifyRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Verify Webauthn sign-in Complete the Webauthn sign-in process by verifying the response from the user’s device. Returns a session if validation is successful.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignInWebauthnVerifyRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

verifySignUpWebauthn()

verifySignUpWebauthn(body: SignUpWebauthnVerifyRequest, options?: RequestInit): Promise<FetchResponse<SessionPayload>>;

Summary: Verify Webauthn sign-up Complete the Webauthn sign-up process by verifying the response from the user’s device. Returns a session if validation is successful.

This method may return different T based on the response code:

• 200: SessionPayload

Parameters

Parameter	Type
body	SignUpWebauthnVerifyRequest
options?	RequestInit

Returns

Promise<FetchResponse<SessionPayload>>

verifyTicketURL()

verifyTicketURL(params?: VerifyTicketParams, options?: RequestInit): string;

Summary: Verify email and authentication tickets Verify tickets created by email verification, magic link authentication, or password reset processes. Redirects the user to the appropriate destination upon successful verification.

As this method is a redirect, it returns a URL string instead of a Promise

Parameters

Parameter	Type
params?	VerifyTicketParams
options?	RequestInit

Returns

string

verifyToken()

verifyToken(body?: VerifyTokenRequest, options?: RequestInit): Promise<FetchResponse<string>>;

Summary: Verify JWT token Verify the validity of a JWT access token. If no request body is provided, the Authorization header will be used for verification.

This method may return different T based on the response code:

• 200: string

Parameters

Parameter	Type
body?	VerifyTokenRequest
options?	RequestInit

Returns

Promise<FetchResponse<string>>

---

CreatePATRequest

Properties

expiresAt

expiresAt: string

(string) - Expiration date of the PAT

• Format - date-time

metadata?

optional metadata: Record<string, unknown>;

Example - {"name":"my-pat","used-by":"my-app-cli"}

---

CreatePATResponse

Properties

id

id: string

(string) - ID of the PAT

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

personalAccessToken

personalAccessToken: string

(string) - PAT

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

---

CredentialAssertionResponse

Properties

authenticatorAttachment?

optional authenticatorAttachment: string;

The authenticator attachment

clientExtensionResults?

optional clientExtensionResults: AuthenticationExtensionsClientOutputs;

Map of extension outputs from the client

id

id: string

(string) - The credential’s identifier

rawId

rawId: string

(string) - Base64url-encoded binary data

• Format - byte

response

response: AuthenticatorAssertionResponse

(AuthenticatorAssertionResponse) -

type

type: string

(string) - The credential type represented by this object

---

CredentialCreationResponse

Properties

authenticatorAttachment?

optional authenticatorAttachment: string;

The authenticator attachment

clientExtensionResults?

optional clientExtensionResults: AuthenticationExtensionsClientOutputs;

Map of extension outputs from the client

id

id: string

(string) - The credential’s identifier

rawId

rawId: string

(string) - Base64url-encoded binary data

• Format - byte

response

response: AuthenticatorAttestationResponse

(AuthenticatorAttestationResponse) -

type

type: string

(string) - The credential type represented by this object

---

CredentialParameter

Properties

alg

alg: number

(number) - The cryptographic algorithm identifier

type

type: 'public-key'

(CredentialType) - The valid credential types

---

CredentialPropertiesOutput

Credential properties extension output

Properties

rk?

optional rk: boolean;

Indicates if the credential is a resident key

---

ErrorResponse

Standardized error response

Properties

error

error: ErrorResponseError

(ErrorResponseError) - Error code identifying the specific application error

message

message: string

(string) - Human-friendly error message

• Example - "Invalid email format"

status

status: number

(number) - HTTP status error code

• Example - 400

---

GetVersionResponse200

Properties

version

version: string

(string) - The version of the authentication service

• Example - "1.2.3"

---

JWK

JSON Web Key for JWT verification

Properties

alg

alg: string

(string) - Algorithm used with this key

• Example - "RS256"

e

e: string

(string) - RSA public exponent

• Example - "AQAB"

kid

kid: string

(string) - Key ID

• Example - "key-id-1"

kty

kty: string

(string) - Key type

• Example - "RSA"

n

n: string

(string) - RSA modulus

• Example - "abcd1234..."

use

use: string

(string) - Key usage

• Example - "sig"

---

JWKSet

JSON Web Key Set for verifying JWT signatures

Properties

keys

keys: JWK[];

(JWK[]) - Array of public keys

---

LinkIdTokenRequest

Properties

idToken

idToken: string

(string) - Apple ID token

nonce?

optional nonce: string;

Nonce used during sign in process

provider

provider: IdTokenProvider

(IdTokenProvider) -

---

MFAChallengePayload

Challenge payload for multi-factor authentication

Properties

ticket

ticket: string

(string) - Ticket to use when completing the MFA challenge

• Example - "mfaTotp:abc123def456"

---

OptionsRedirectTo

Properties

redirectTo?

optional redirectTo: string;

Example - "https://my-app.com/catch-redirection" Format - uri

---

ProviderSession

OAuth2 provider session containing access and refresh tokens

Properties

accessToken

accessToken: string

(string) - OAuth2 provider access token for API calls

• Example - "ya29.a0AfH6SMBx..."

expiresAt

expiresAt: string

(string) - Timestamp when the access token expires

• Example - "2024-12-31T23:59:59Z"
• Format - date-time

expiresIn

expiresIn: number

(number) - Number of seconds until the access token expires

• Example - 3599

refreshToken?

optional refreshToken: string;

OAuth2 provider refresh token for obtaining new access tokens (if provided by the provider) Example - "1//0gK8..."

---

ProviderSpecificParams

Properties

connection?

optional connection: string;

(workos) Specifies the connection to use for authentication

organization?

optional organization: string;

(workos) Specifies the organization to use for authentication

---

PublicKeyCredentialCreationOptions

Properties

attestation?

optional attestation: ConveyancePreference;

The attestation conveyance preference

attestationFormats?

optional attestationFormats: AttestationFormat[];

The preferred attestation statement formats

authenticatorSelection?

optional authenticatorSelection: AuthenticatorSelection;

challenge

challenge: string

(string) - Base64url-encoded binary data

• Format - byte

excludeCredentials?

optional excludeCredentials: PublicKeyCredentialDescriptor[];

A list of PublicKeyCredentialDescriptor objects representing public key credentials that are not acceptable to the caller

extensions?

optional extensions: Record<string, unknown>;

Additional parameters requesting additional processing by the client and authenticator

hints?

optional hints: PublicKeyCredentialHints[];

Hints to help guide the user through the experience

pubKeyCredParams

pubKeyCredParams: CredentialParameter[];

(CredentialParameter[]) - The desired credential types and their respective cryptographic parameters

rp

rp: RelyingPartyEntity

(RelyingPartyEntity) -

timeout?

optional timeout: number;

A time, in milliseconds, that the caller is willing to wait for the call to complete

user

user: UserEntity

(UserEntity) -

---

PublicKeyCredentialDescriptor

Properties

id

id: string

(string) - Base64url-encoded binary data

• Format - byte

transports?

optional transports: AuthenticatorTransport[];

The authenticator transports that can be used

type

type: 'public-key'

(CredentialType) - The valid credential types

---

PublicKeyCredentialRequestOptions

Properties

allowCredentials?

optional allowCredentials: PublicKeyCredentialDescriptor[];

A list of CredentialDescriptor objects representing public key credentials acceptable to the caller

challenge

challenge: string

(string) - Base64url-encoded binary data

• Format - byte

extensions?

optional extensions: Record<string, unknown>;

Additional parameters requesting additional processing by the client and authenticator

hints?

optional hints: PublicKeyCredentialHints[];

Hints to help guide the user through the experience

rpId?

optional rpId: string;

The RP ID the credential should be scoped to

timeout?

optional timeout: number;

A time, in milliseconds, that the caller is willing to wait for the call to complete

userVerification?

optional userVerification: UserVerificationRequirement;

A requirement for user verification for the operation

---

RefreshProviderTokenRequest

Request to refresh OAuth2 provider tokens

Properties

refreshToken

refreshToken: string

(string) - OAuth2 provider refresh token obtained from previous authentication

• Example - "1//0gK8..."

---

RefreshTokenRequest

Request to refresh an access token

Properties

refreshToken

refreshToken: string

(string) - Refresh token used to generate a new access token

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

---

RelyingPartyEntity

Properties

id

id: string

(string) - A unique identifier for the Relying Party entity, which sets the RP ID

name

name: string

(string) - A human-palatable name for the entity

---

Session

User authentication session containing tokens and user information

Extended by

• Session

Properties

accessToken

accessToken: string

(string) - JWT token for authenticating API requests

• Example - "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

accessTokenExpiresIn

accessTokenExpiresIn: number

(number) - Expiration time of the access token in seconds

• Example - 900
• Format - int64

refreshToken

refreshToken: string

(string) - Token used to refresh the access token

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

refreshTokenId

refreshTokenId: string

(string) - Identifier for the refresh token

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

user?

optional user: User;

User profile and account information

---

SessionPayload

Container for session information

Properties

session?

optional session: Session;

User authentication session containing tokens and user information

---

SignInAnonymousRequest

Properties

displayName?

optional displayName: string;

Example - "John Smith"

locale?

optional locale: string;

A two or three characters locale Example - "en" MinLength - 2 MaxLength - 3

metadata?

optional metadata: Record<string, unknown>;

Example - {"firstName":"John","lastName":"Smith"}

---

SignInEmailPasswordRequest

Request to authenticate using email and password

Properties

email

email: string

(string) - User’s email address

• Example - "[email protected]"
• Format - email

password

password: string

(string) - User’s password

• Example - "Str0ngPassw#ord-94|%"
• MinLength - 3
• MaxLength - 50

---

SignInEmailPasswordResponse

Response for email-password authentication that may include a session or MFA challenge

Properties

mfa?

optional mfa: MFAChallengePayload;

Challenge payload for multi-factor authentication

session?

optional session: Session;

User authentication session containing tokens and user information

---

SignInIdTokenRequest

Properties

idToken

idToken: string

(string) - Apple ID token

nonce?

optional nonce: string;

Nonce used during sign in process

options?

optional options: SignUpOptions;

provider

provider: IdTokenProvider

(IdTokenProvider) -

---

SignInMfaTotpRequest

Properties

otp

otp: string

(string) - One time password

ticket

ticket: string

(string) - Ticket

• Pattern - ^mfaTotp:.*$

---

SignInOTPEmailRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: SignUpOptions;

---

SignInOTPEmailVerifyRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

otp

otp: string

(string) - One time password

---

SignInOTPEmailVerifyResponse

Properties

session?

optional session: Session;

User authentication session containing tokens and user information

---

SignInPasswordlessEmailRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: SignUpOptions;

---

SignInPasswordlessSmsOtpRequest

Properties

otp

otp: string

(string) - One-time password received by SMS

phoneNumber

phoneNumber: string

(string) - Phone number of the user

• Example - "+123456789"

---

SignInPasswordlessSmsOtpResponse

Properties

mfa?

optional mfa: MFAChallengePayload;

Challenge payload for multi-factor authentication

session?

optional session: Session;

User authentication session containing tokens and user information

---

SignInPasswordlessSmsRequest

Properties

options?

optional options: SignUpOptions;

phoneNumber

phoneNumber: string

(string) - Phone number of the user

• Example - "+123456789"

---

SignInPATRequest

Properties

personalAccessToken

personalAccessToken: string

(string) - PAT

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

---

SignInProviderParams

Parameters for the signInProvider method.

Properties

allowedRoles?

optional allowedRoles: string[];

Array of allowed roles for the user

connect?

optional connect: string;

If set, this means that the user is already authenticated and wants to link their account. This needs to be a valid JWT access token.

defaultRole?

optional defaultRole: string;

Default role for the user

displayName?

optional displayName: string;

Display name for the user

locale?

optional locale: string;

A two or three characters locale

metadata?

optional metadata: Record<string, unknown>;

Additional metadata for the user (JSON encoded string)

providerSpecificParams?

optional providerSpecificParams: ProviderSpecificParams;

Additional provider-specific parameters

redirectTo?

optional redirectTo: string;

URI to redirect to

state?

optional state: string;

Opaque state value to be returned by the provider

---

SignInWebauthnRequest

Properties

email?

optional email: string;

A valid email Example - "[email protected]" Format - email

---

SignInWebauthnVerifyRequest

Properties

credential

credential: CredentialAssertionResponse

(CredentialAssertionResponse) -

email?

optional email: string;

A valid email. Deprecated, no longer used Example - "[email protected]" Format - email

---

SignOutRequest

Properties

all?

optional all: boolean;

Sign out from all connected devices

refreshToken?

optional refreshToken: string;

Refresh token for the current session

---

SignUpEmailPasswordRequest

Request to register a new user with email and password

Properties

email

email: string

(string) - Email address for the new user account

• Example - "[email protected]"
• Format - email

options?

optional options: SignUpOptions;

password

password: string

(string) - Password for the new user account

• Example - "Str0ngPassw#ord-94|%"
• MinLength - 3
• MaxLength - 50

---

SignUpOptions

Properties

allowedRoles?

optional allowedRoles: string[];

Example - ["me","user"]

defaultRole?

optional defaultRole: string;

Example - "user"

displayName?

optional displayName: string;

Example - "John Smith" Pattern - ^[\p{L}\p{N}\p{S} ,.’-]+$ MaxLength - 32

locale?

optional locale: string;

A two or three characters locale Example - "en" MinLength - 2 MaxLength - 3

metadata?

optional metadata: Record<string, unknown>;

Example - {"firstName":"John","lastName":"Smith"}

redirectTo?

optional redirectTo: string;

Example - "https://my-app.com/catch-redirection" Format - uri

---

SignUpWebauthnRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: SignUpOptions;

---

SignUpWebauthnVerifyRequest

Properties

credential

credential: CredentialCreationResponse

(CredentialCreationResponse) -

nickname?

optional nickname: string;

Nickname for the security key

options?

optional options: SignUpOptions;

---

TotpGenerateResponse

Response containing TOTP setup information for MFA

Properties

imageUrl

imageUrl: string

(string) - URL to QR code image for scanning with an authenticator app

• Example - "data:image/png;base64,iVBORw0KGg..."

totpSecret

totpSecret: string

(string) - TOTP secret key for manual setup with an authenticator app

• Example - "ABCDEFGHIJK23456"

---

User

User profile and account information

Properties

activeMfaType?

optional activeMfaType: string;

Active MFA type for the user

avatarUrl

avatarUrl: string

(string) - URL to the user’s profile picture

• Example - "https://myapp.com/avatars/user123.jpg"

createdAt

createdAt: string

(string) - Timestamp when the user account was created

• Example - "2023-01-15T12:34:56Z"
• Format - date-time

defaultRole

defaultRole: string

(string) - Default authorization role for the user

• Example - "user"

displayName

displayName: string

(string) - User’s display name

• Example - "John Smith"

email?

optional email: string;

User’s email address Example - "[email protected]" Format - email

emailVerified

emailVerified: boolean

(boolean) - Whether the user’s email has been verified

• Example - true

id

id: string

(string) - Unique identifier for the user

• Example - "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24"
• Pattern - \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b

isAnonymous

isAnonymous: boolean

(boolean) - Whether this is an anonymous user account

• Example - false

locale

locale: string

(string) - User’s preferred locale (language code)

• Example - "en"
• MinLength - 2
• MaxLength - 3

metadata

metadata: Record<string, unknown>

(Record<string, unknown>) - Custom metadata associated with the user

• Example - {"firstName":"John","lastName":"Smith"}

phoneNumber?

optional phoneNumber: string;

User’s phone number Example - "+12025550123"

phoneNumberVerified

phoneNumberVerified: boolean

(boolean) - Whether the user’s phone number has been verified

• Example - false

roles

roles: string[];

(string[]) - List of roles assigned to the user

• Example - ["user","customer"]

---

UserDeanonymizeRequest

Properties

connection?

optional connection: string;

Deprecated, will be ignored

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: SignUpOptions;

password?

optional password: string;

A password of minimum 3 characters Example - "Str0ngPassw#ord-94|%" MinLength - 3 MaxLength - 50

signInMethod

signInMethod: UserDeanonymizeRequestSignInMethod

(UserDeanonymizeRequestSignInMethod) - Which sign-in method to use

---

UserEmailChangeRequest

Properties

newEmail

newEmail: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: OptionsRedirectTo;

---

UserEmailSendVerificationEmailRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: OptionsRedirectTo;

---

UserEntity

Properties

displayName

displayName: string

(string) - A human-palatable name for the user account, intended only for display

id

id: string

(string) - The user handle of the user account entity

name

name: string

(string) - A human-palatable name for the entity

---

UserMfaRequest

Request to activate or deactivate multi-factor authentication

Properties

activeMfaType?

optional activeMfaType: UserMfaRequestActiveMfaType;

Type of MFA to activate. Use empty string to disable MFA. Example - "totp"

code

code: string

(string) - Verification code from the authenticator app when activating MFA

• Example - "123456"

---

UserPasswordRequest

Properties

newPassword

newPassword: string

(string) - A password of minimum 3 characters

• Example - "Str0ngPassw#ord-94|%"
• MinLength - 3
• MaxLength - 50

ticket?

optional ticket: string;

Ticket to reset the password, required if the user is not authenticated Pattern - ^passwordReset:.*$

---

UserPasswordResetRequest

Properties

email

email: string

(string) - A valid email

• Example - "[email protected]"
• Format - email

options?

optional options: OptionsRedirectTo;

---

VerifyAddSecurityKeyRequest

Properties

credential

credential: CredentialCreationResponse

(CredentialCreationResponse) -

nickname?

optional nickname: string;

Optional nickname for the security key

---

VerifyAddSecurityKeyResponse

Properties

id

id: string

(string) - The ID of the newly added security key

• Example - "123e4567-e89b-12d3-a456-426614174000"

nickname?

optional nickname: string;

The nickname of the security key if provided

---

VerifyTicketParams

Parameters for the verifyTicket method.

Properties

redirectTo

redirectTo: string

(RedirectToQuery) - Target URL for the redirect

• Target URL for the redirect

ticket

ticket: string

(TicketQuery) - Ticket

• Ticket

type?

optional type: TicketTypeQuery;

Type of the ticket. Deprecated, no longer used

• Type of the ticket

---

VerifyTokenRequest

Properties

token?

optional token: string;

JWT token to verify

Type Aliases

AttestationFormat

type AttestationFormat =
  | 'packed'
  | 'tpm'
  | 'android-key'
  | 'android-safetynet'
  | 'fido-u2f'
  | 'apple'
  | 'none'

The attestation statement format

---

AuthenticatorAttachment

type AuthenticatorAttachment = 'platform' | 'cross-platform'

The authenticator attachment modality

---

AuthenticatorTransport

type AuthenticatorTransport = 'usb' | 'nfc' | 'ble' | 'smart-card' | 'hybrid' | 'internal'

The authenticator transports that can be used

---

ConveyancePreference

type ConveyancePreference = 'none' | 'indirect' | 'direct' | 'enterprise'

The attestation conveyance preference

---

CredentialType

type CredentialType = 'public-key'

The valid credential types

---

ErrorResponseError

type ErrorResponseError =
  | 'default-role-must-be-in-allowed-roles'
  | 'disabled-endpoint'
  | 'disabled-user'
  | 'email-already-in-use'
  | 'email-already-verified'
  | 'forbidden-anonymous'
  | 'internal-server-error'
  | 'invalid-email-password'
  | 'invalid-request'
  | 'locale-not-allowed'
  | 'password-too-short'
  | 'password-in-hibp-database'
  | 'redirectTo-not-allowed'
  | 'role-not-allowed'
  | 'signup-disabled'
  | 'unverified-user'
  | 'user-not-anonymous'
  | 'invalid-pat'
  | 'invalid-refresh-token'
  | 'invalid-ticket'
  | 'disabled-mfa-totp'
  | 'no-totp-secret'
  | 'invalid-totp'
  | 'mfa-type-not-found'
  | 'totp-already-active'
  | 'invalid-state'
  | 'oauth-token-echange-failed'
  | 'oauth-profile-fetch-failed'
  | 'oauth-provider-error'
  | 'invalid-otp'
  | 'cannot-send-sms'
  | 'provider-account-already-linked'

Error code identifying the specific application error

---

IdTokenProvider

type IdTokenProvider = 'apple' | 'google'

---

OKResponse

type OKResponse = 'OK'

---

PublicKeyCredentialHints

type PublicKeyCredentialHints = 'security-key' | 'client-device' | 'hybrid'

Hints to help guide the user through the experience

---

RedirectToQuery

type RedirectToQuery = string

Target URL for the redirect

---

ResidentKeyRequirement

type ResidentKeyRequirement = 'discouraged' | 'preferred' | 'required'

The resident key requirement

---

SignInProvider

type SignInProvider =
  | 'apple'
  | 'github'
  | 'google'
  | 'linkedin'
  | 'discord'
  | 'spotify'
  | 'twitch'
  | 'gitlab'
  | 'bitbucket'
  | 'workos'
  | 'azuread'
  | 'entraid'
  | 'strava'
  | 'facebook'
  | 'windowslive'
  | 'twitter'

---

TicketQuery

type TicketQuery = string

Ticket

---

TicketTypeQuery

type TicketTypeQuery = 'emailVerify' | 'emailConfirmChange' | 'signinPasswordless' | 'passwordReset'

Type of the ticket

---

URLEncodedBase64

type URLEncodedBase64 = string

Base64url-encoded binary data

---

UserDeanonymizeRequestSignInMethod

type UserDeanonymizeRequestSignInMethod = 'email-password' | 'passwordless'

Which sign-in method to use

---

UserMfaRequestActiveMfaType

type UserMfaRequestActiveMfaType = 'totp' | ''

Type of MFA to activate. Use empty string to disable MFA.

---

UserVerificationRequirement

type UserVerificationRequirement = 'required' | 'preferred' | 'discouraged'

A requirement for user verification for the operation

Functions

createAPIClient()

function createAPIClient(baseURL: string, chainFunctions: ChainFunction[]): Client

Parameters

Parameter	Type	Default value
baseURL	string	undefined
chainFunctions	ChainFunction[]	[]

Returns

Client