Skip to main content
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.
​
api.access.deny(code, reason)
void
Mark the current token exchange as denied.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.access.deny('invalid_request', 'Client is not authorized for this grant.');
};
Parameters

​
api.accessToken

Request changes to the access token being issued.
​
api.accessToken.setCustomClaim(key, value)
void
Set a custom claim on the access token that will be issued.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim('https://example.com/role', 'admin');
};
Parameters

​
api.transaction

Make changes to the transaction scopes.
​
api.transaction.addTargetScope(scope)
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.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.addTargetScope('read:reports');
};
Parameters
​
api.transaction.removeTargetScope(scope)
void
Remove a scope from the target scope set.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.removeTargetScope('admin:full');
};
Parameters
​
api.transaction.setTargetScopes(scopes)
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.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.setTargetScopes(['read:users', 'write:users']);
};
Parameters
​
api.transaction.clearTargetScopes()
void
Remove all scopes from the target scope set.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.transaction.clearTargetScopes();
};

​
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.onExecuteCredentialsExchange = async (event, api) => {
  api.cache.delete('my-key');
};
Parameters
​
api.cache.get(key)
object | undefined
Retrieve a cached record at the supplied key. If found, access the value via record.value.
Example
exports.onExecuteCredentialsExchange = async (event, api) => {
  const record = api.cache.get('my-key');
  if (record) console.log(record.value);
};
Parameters
​
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.onExecuteCredentialsExchange = async (event, api) => {
  api.cache.set('my-key', 'my-value', { ttl: 60000 });
};
Parameters