API Object

Learn about the custom-token-exchange Action trigger’s API object.

The API object for the custom-token-exchange Actions trigger exposes methods for controlling access, authenticating users, managing metadata, and caching data.

api.access

Modify the access of the token exchange request, such as rejecting the request.

api.access.deny(code, reason) · void

Mark the current token exchange as denied.

If the request is being denied due to an invalid subject token, use api.access.rejectInvalidSubjectToken instead to distinguish brute force attempts from other denial reasons.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }
};

Parameters

Show Parameters

code · string

The error code justifying the rejection. Can be invalid_request, server_error, or any custom code.

reason · string

A human-readable explanation for rejecting the token exchange request.

api.access.rejectInvalidSubjectToken(reason) · void

Mark the provided subject token as invalid. This rejects the request with an invalid_request error and signals Attack Protection features to apply brute force protections.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  try {
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    api.authentication.setUserById(subject_token.id);
  } catch (error) {
    if (error.message === 'Invalid Token') {
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      throw error;
    }
  }
};

Parameters

Show Parameters

reason · string

A human-readable explanation for rejecting the token exchange request.

api.authentication

Indicate the result of the authentication of the subject token, specifying the user for whom tokens will be issued.

api.authentication.setUserById(user_id) · void

Indicate the user corresponding to the subject token by providing their user ID. Exactly one of setUserById or setUserByConnection must be called.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  api.authentication.setUserById(subject_token.sub);
};

Parameters

Show Parameters

user_id · string

The ID of the user; must be an existing user.

api.authentication.setUserByConnection(connection_name, user_attributes, options) · void

Indicate the user corresponding to the subject token by providing a connection and user attributes. Creates the user if they don’t exist. Exactly one of setUserById or setUserByConnection must be called.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
  api.authentication.setUserByConnection(
    'My Connection',
    { user_id: subject_token.sub, email: subject_token.email, email_verified: true },
    { creationBehavior: 'create_if_not_exists', updateBehavior: 'none' }
  );
};

Parameters

Show Parameters

connection_name · string

Name of the connection the user should be stored in.

user_attributes · object

The user’s profile attributes. The user_id field is required and used to determine if the user exists.

Show user_attributes properties

user_id · string

The user’s unique identifier within the connection. Required.

email · string

Optional. The user’s email.

email_verified · boolean

Optional. Whether the email address is verified.

family_name · string

Optional. The user’s family name.

given_name · string

Optional. The user’s given name.

name · string

Optional. The user’s full name.

nickname · string

Optional. The user’s nickname.

phone_number · string

Optional. The user’s phone number (E.164 format).

phone_verified · boolean

Optional. Whether the phone number is verified.

picture · string

Optional. A URI pointing to the user’s picture.

username · string

Optional. The user’s username.

verify_email · boolean

Optional. Whether to send a verification email after creation.

options · object

Options to control behavior of the command.

Show options properties

creationBehavior · string

Behavior when the user does not exist. Allowed values: create_if_not_exists, none.

updateBehavior · string

Behavior when the user already exists. Allowed values: none, replace.

api.authentication.setOrganization(organization_id_or_name) · void

Set the organization for the user associated with the token exchange.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  api.authentication.setOrganization('org_xS525r979AS33MSf');
  api.authentication.setUserById(subject_token.sub);
};

Parameters

Show Parameters

organization_id_or_name · string

The ID or name of the organization to set for the user.

api.authentication.setActor(actor) · void

Set the actor for the token exchange to represent the entity acting on behalf of the subject. Calling setActor is optional. Refresh tokens are not issued when an actor is set.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  const actor_token = await validateToken(event.transaction.actor_token, jwksUri);
  api.authentication.setActor({ sub: actor_token.sub });
  api.authentication.setUserById(subject_token.sub);
};

Parameters

Show Parameters

actor · object

A nested object representing a delegation chain. The sub field is required; up to 5 additional custom properties may be provided per level, up to 4 additional act levels.

Show actor properties

sub · string

The subject of the actor. Required.

act · object

Optional nested actor for delegation chains.

api.user

Request changes to the user corresponding to the subject token.

api.user.setAppMetadata(key, value) · void

Set application-specific metadata for the user corresponding to the subject token.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  api.user.setAppMetadata('group', subject_token.group);
};

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. This may be set to null to remove the metadata property.

api.user.setUserMetadata(key, value) · void

Set general metadata for the user corresponding to the subject token.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  api.user.setUserMetadata('preferred_locale', subject_token.locale);
};

Parameters

Show Parameters

key · string

The metadata property to be set.

value · unknown

The value of the metadata property. This may be set to null to remove the metadata property.

api.cache

Store and retrieve data that persists across executions.

api.cache.delete(key) · void

Delete a cached record at the supplied key if it exists.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  api.cache.delete('my-key');
};

Parameters

Show Parameters

key · string

The key of the cache record to delete.

api.cache.get(key) · object | undefined

Retrieve a cached record at the supplied key. If found, access the value via record.value.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  const record = api.cache.get('my-key');
  if (record) console.log(record.value);
};

Parameters

Show Parameters

key · string

The key of the record stored in the cache.

api.cache.set(key, value, options) · void

Store or update a string value in the cache at the specified key. Values are scoped to the Trigger and subject to the Actions Cache Limits. If no lifetime is specified, a default lifetime of 15 minutes will be used.

Important: This cache is designed for short-lived, ephemeral data. Items may not be available in later transactions even if they are within their supplied lifetime.

Example

exports.onExecuteCustomTokenExchange = async (event, api) => {
  api.cache.set('my-key', 'my-value', { ttl: 60000 });
};

Parameters

Show Parameters

key · string

The key of the record to be stored.

value · string

The value of the record to be stored.

options · CacheSetOptions

Options for adjusting cache behavior. Optional.

Show options properties

expires_at · number

The absolute expiry time in milliseconds since the unix epoch. Note: Do not supply if ttl is also provided; the earlier expiry will be used.

ttl · number

The time-to-live in milliseconds. Note: Do not supply if expires_at is also provided; the earlier expiry will be used.