> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn about the credentials-exchange Action trigger's API object.

# API Object

The API object for the credentials-exchange Actions trigger exposes methods for controlling access, customizing the access token, managing scopes, and caching data.

## `api.access`

Control availability of the access token.

<ParamField body="api.access.deny(code, reason)" type="void">
  Mark the current token exchange as denied.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.access.deny('invalid_request', 'Client is not authorized for this grant.');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="code" type="string">
      The protocol-specific error code justifying the rejection. Allowed values: `invalid_scope`, `invalid_request`, `server_error`.
    </ParamField>

    <ParamField body="reason" type="string">
      A human-readable explanation for rejecting the access token grant. Optional.
    </ParamField>
  </Expandable>
</ParamField>

## `api.accessToken`

Request changes to the access token being issued.

<ParamField body="api.accessToken.setCustomClaim(key, value)" type="void">
  Set a custom claim on the access token that will be issued.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.accessToken.setCustomClaim('https://example.com/role', 'admin');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      Name of the claim (note that this may need to be a fully-qualified URL).
    </ParamField>

    <ParamField body="value" type="unknown">
      The value of the claim.
    </ParamField>
  </Expandable>
</ParamField>

## `api.transaction`

Make changes to the transaction scopes.

<ParamField body="api.transaction.addTargetScope(scope)" type="void">
  Add a scope to the target scope set. Added scopes are intersected with the client grant after all Actions complete. Scopes not present in the grant are silently dropped from the final access token.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.transaction.addTargetScope('read:reports');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="scope" type="string">
      The scope to add.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.transaction.removeTargetScope(scope)" type="void">
  Remove a scope from the target scope set.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.transaction.removeTargetScope('admin:full');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="scope" type="string">
      The scope to remove.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.transaction.setTargetScopes(scopes)" type="void">
  Replace the entire target scope set. The new scopes are intersected with the client grant after all Actions complete. Scopes not present in the grant are silently dropped from the final access token.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.transaction.setTargetScopes(['read:users', 'write:users']);
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="scopes" type="array of strings">
      The new target scope set.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.transaction.clearTargetScopes()" type="void">
  Remove all scopes from the target scope set.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.transaction.clearTargetScopes();
  };
  ```
</ParamField>

## `api.cache`

Store and retrieve data that persists across executions.

<ParamField body="api.cache.delete(key)" type="void">
  Delete a cached record at the supplied key if it exists.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.cache.delete('my-key');
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the cache record to delete.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.get(key)" type="object | undefined">
  Retrieve a cached record at the supplied key. If found, access the value via `record.value`.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    const record = api.cache.get('my-key');
    if (record) console.log(record.value);
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record stored in the cache.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="api.cache.set(key, value, options)" type="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](https://auth0.com/docs/customize/actions/limitations). 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.

  ```js Example theme={null}
  exports.onExecuteCredentialsExchange = async (event, api) => {
    api.cache.set('my-key', 'my-value', { ttl: 60000 });
  };
  ```

  **Parameters**

  <Expandable title="Parameters">
    <ParamField body="key" type="string">
      The key of the record to be stored.
    </ParamField>

    <ParamField body="value" type="string">
      The value of the record to be stored.
    </ParamField>

    <ParamField body="options" type="CacheSetOptions">
      Options for adjusting cache behavior. Optional.

      <Expandable title="options properties">
        <ParamField body="expires_at" type="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.
        </ParamField>

        <ParamField body="ttl" type="number">
          The time-to-live in milliseconds. *Note*: Do not supply if `expires_at` is also provided; the earlier expiry will be used.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>