API Reference

createAuthorizationUrl(options)

Creates an OAuth authorization URL.

Parameters

• options (object):
  • codeChallenge (string, required): The code challenge for PKCE
  • redirectUrl (string, required if multiple redirect URLs are configured): The redirect URL for the OAuth flow. Must match one of the URLs configured in your integration dashboard.
  • scope (string, optional): The OAuth scope. Defaults to 'verification openid age ...'
  • state (string, optional): A state parameter for security
  • nonce (string, optional): A nonce for security

Returns

string: The complete authorization URL

parseRedirectUrl()

Parses the OAuth redirect URL and extracts parameters.

Returns

object: An object containing:

• code (string): The authorization code
• state (string): The state parameter (if provided)
• error (string): Error code if authorization failed
• errorDescription (string): Error description if authorization failed

createCodeChallenge(codeVerifier)

Creates a PKCE code challenge from a code verifier.

Parameters

• codeVerifier (string, optional): The code verifier. If not provided, a random one will be generated.

Returns

object: An object containing:

• codeVerifier (string): The code verifier
• codeChallenge (string): The generated code challenge

exchangeCodeForTokens(options)

Exchanges an authorization code for access and refresh tokens.

Parameters

• options (object):
  • code (string, required): The authorization code
  • codeVerifier (string, required): The code verifier
  • redirectUri (string, required): The redirect URI used in the authorization request

Returns

Promise: The token response containing:

• access_token (string): The access token
• refresh_token (string): The refresh token
• id_token (string): The OIDC ID token
• expires_in (number): Token expiration time in seconds
• scope (string): Space-separated list of granted scopes
• sub (string): Unique user identifier
• token_type (string): Always "Bearer"

getUserInfo(accessToken, timezone)

Retrieves user information using an access token.

Parameters

• accessToken (string, required): The access token
• timezone (string, optional): The timezone to use when age is included

Returns

Promise: The user information object containing:

• sub (string): Unique user identifier
• verified (boolean): Whether the user is verified
• verification_confidence (number): Confidence level (1-3)
• age (number): User's age (if requested)
• regional_info (object): Regional information (if requested) containing:
  • region (string): User's region
  • additional_userinfo_url (string): URL for additional regional information

getRegionalUserInfo(accessToken, regionalUrl)

Retrieves user's regional information using an access token.

Parameters

• accessToken (string, required): The access token
• regionalUrl (string, required): The regional URL

Returns

Promise: The regional user information object containing:

• sub (string): Unique user identifier
• name (object): User's name information containing:
  • firstName (string, optional): User's first name
  • middleNames (array of strings, optional): Array of user's middle names
  • lastName (string, optional): User's last name
  • suffix (string, optional): The suffix portion of the user's name
  • fullName (string, optional): User's full name with an attempt at localization
• date_of_birth (string): User's date of birth
• id_type (object): Information about the ID used containing:
  • country (string): 3-letter country code that issued the ID
  • type (string): Type of ID (e.g., 'state_id', 'passport')
  • state (string, optional): 2-letter state code that issued the ID (if applicable)

validateIdToken(idToken, nonce)

Validates an ID token.

Parameters

• idToken (string, required): The ID token to validate
• nonce (string, optional): The nonce used in the authorization request

Returns

Promise: The validated token claims

• iss (string): The issuer (https://api.universalverify.com)
• sub (string): An ID for the user unique to the integration
• aud (string): Your integration's access key
• exp (number): The token's expiration time (unix time)
• iat (number): The issued at time (unix time)
• verified (boolean): Whether the user is verified
• verification_confidence (number): Confidence level (1-3)

refreshToken(refreshToken)

Refreshes an access token using a refresh token.

Parameters

• refreshToken (string, required): The refresh token

Returns

Promise: The new token response containing:

• access_token (string): The new access token
• refresh_token (string): The new refresh token
• expires_in (number): Token expiration time in seconds
• scope (string): Space-separated list of granted scopes
• sub (string): Unique user identifier
• token_type (string): Always "Bearer"

verifyWebhookSignature(payload, signature, webhookSecret)

Verifies a webhook signature and returns the parsed payload.

Parameters

• payload (string, required): The webhook payload
• signature (string, required): The webhook signature
• webhookSecret (string, required): Your webhook secret

Returns

object: The webhook's request body parameters containing:

• type (string): The event type (e.g. 'user.verification.updated')
• data (object): The event-specific data

Throws

Error: If the webhook signature is invalid

revokeToken(token)

Revokes an access or refresh token.

Parameters

• token (string, required): The token to revoke

Returns

Promise: The revocation result