> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/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 includes:

## `api.access`

Control availability to the access token.

### `api.access.deny(code, reason)`

Mark the current token exchange as denied.

**Parameters**

<Expandable title="Parameters" defaultOpen>
  <ParamField body="code" type="string">
    The protocol-specific error code justifying the rejection of the login.
    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>

## `api.accessToken`

Request changes to the access token being issued.

### `api.accessToken.setCustomClaim(key, value)`

Set a custom claim on the Access Token that will be issued.

**Parameters**

<Expandable title="Parameters" defaultOpen>
  <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>

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

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

**Parameters**

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

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

**Parameters**

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

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 15 minutes will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**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 their lifetime.

**Parameters**

<Expandable title="Parameters" defaultOpen>
  <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.
        While cached records may be evicted earlier, they will
        never remain beyond the supplied `expires_at`.

        *Note*: This value should not be supplied if a value was also
        provided for `ttl`. If both options are supplied, the
        earlier expiry of the two will be used.
        Optional.
      </ParamField>

      <ParamField body="ttl" type="number">
        The time-to-live value of this cache entry in milliseconds.
        While cached values may be evicted earlier, they will
        never remain beyond the supplied `ttl`.

        *Note*: This value should not be supplied if a value was also
        provided for `expires_at`. If both options are supplied, the
        earlier expiry of the two will be used.
        Optional.
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

## `api.transaction`

\[Early Access] Make changes to the transaction.

### `api.transaction.addTargetScope(scope)`

\[Early Access] 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 theme={null}
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.addTargetScope('read:reports');
};
```

**Parameters**

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

### `api.transaction.removeTargetScope(scope)`

\[Early Access] Remove a scope from the target scope set.

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

**Parameters**

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

### `api.transaction.setTargetScopes(scopes)`

\[Early Access] 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 theme={null}
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.setTargetScopes(['read:users', 'write:users']);
};
```

**Parameters**

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

### `api.transaction.clearTargetScopes()`

\[Early Access] Remove all scopes from the target scope set.

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