Authenticate Actions and Store Credentials Securely

Actions connect your agents to external systems. Simple provides encrypted configuration variables for credentials and managed OAuth connections for service-to-service APIs, so you can keep authentication separate from conversation inputs and Action source code.

Choose an Authentication Method

Your API requires	Use
OAuth 2.0 client credentials	A managed OAuth connection explicitly chosen for each fetch. Simple manages the access token.
An API key, static bearer token, or Basic authentication	A sensitive configuration variable referenced in an HTTP Action or Code Action.
An interactive OAuth sign-in or user consent	Your application’s OAuth flow or middleware; managed connections support the client-credentials grant.
A signed request or custom token exchange	A Code Action or your own middleware.
A client certificate for mTLS	Middleware configured with the certificate and private key.

Managed OAuth Connections

An OAuth connection is a reusable configuration owned by your organization. In your Code Action, you explicitly choose the connection to use on each fetch that needs authentication. Saving a connection or making it available to an Action does not add credentials to requests automatically. A fetch without an explicit connection selection receives no managed OAuth credential, even when its URL matches a saved connection’s allowed origins. Simple does not infer the credential from the destination or reuse the selection from a previous fetch. When you choose a connection for a request, Simple manages its token exchange and renewal. Your code selects the connection without copying its client secret or access token into source code. The supported grant is OAuth 2.0 client credentials (client_credentials): your agent acts on behalf of a service account or application. This does not implement a user’s browser sign-in, authorization-code callback, or refresh-token grant.

Create a Connection

Open Configuration → OAuth Connections and add a connection.
Enter a descriptive name and the provider settings below.
Save the connection and use its test control to verify that the provider issues a token.

Setting	What to enter
Token URL	The provider’s HTTPS token endpoint, such as `https://auth.example.com/oauth/token`.
Client ID	The identifier issued for your application or service account.
Client secret	The secret issued by the provider. This is a write-only field.
Client authentication method	HTTP Basic (`client_secret_basic`) or Form body (`client_secret_post`), as required by the provider. This controls the token request, not the API request.
Scopes	The provider’s permission scopes, separated by spaces.
Audience / Resource	Optional identifiers required by your provider for the target API.
Extra token parameters	Optional provider-specific values, one `KEY=value` per line. These cannot override the dedicated grant, client credential, scope, audience, or resource settings.
Allowed origins	The HTTPS API origins that may receive this connection’s token, one per line, such as `https://api.example.com`.

Extra token parameters and other connection settings are readable configuration. Put the client secret in its dedicated field; do not store additional secrets in descriptions, URLs, or extra token parameters.

Choose Authentication on Each Fetch

For every fetch in your Code Action, decide whether it needs managed authentication and explicitly choose the saved connection if it does. Selection applies only to that request. For example, a Code Action that calls the same CRM API twice can:

Fetch a public endpoint without choosing authentication. No managed OAuth token is added.
Fetch a protected account endpoint and explicitly choose the Production CRM connection for that request.

A second authenticated fetch must choose its connection again. Allowed origins constrain where the selected credential may be sent; they do not select or enable authentication. Simple continues to handle the selected connection’s token lifecycle and keeps managed secrets out of Action code.

Example: Choose an OAuth Connection in Code

With a saved OAuth connection named production-crm that allows https://api.example.com, explicitly choose it for the request:

import { defineAction } from '@simple-ai-lab/sdk';

export default defineAction(async ({ auth }) => {
  const response = await auth.fetch('https://api.example.com/customers', {
    connection: 'production-crm',
    method: 'GET',
  });

  if (!response.ok) {
    throw new Error(`Customer lookup failed: ${response.status}`);
  }

  return { customers: await response.json() };
});

Each auth.fetch explicitly names the saved OAuth connection. Simple handles token acquisition, renewal, and secure attachment for that request. Another authenticated request must select its connection again. Ordinary fetch(...) receives no managed OAuth credentials.

How Tokens Are Obtained and Renewed

Your code explicitly selects a connection for the fetch. Simple verifies that the selected connection exists, belongs to the organization executing the Action, and permits the destination origin.
Simple reuses a cached token when it is sufficiently far from expiry. Otherwise, it exchanges the stored client credentials at the provider’s token endpoint.
The access token is encrypted before it is cached. Concurrent requests coordinate token renewal to reduce duplicate exchanges.
Simple attaches the selected connection’s token only to that explicitly authenticated request. Other fetches receive no managed OAuth credential unless they also select a connection.

Simple stops reusing a cached token within 60 seconds of its expiry and obtains a replacement when needed. Renewal is another client-credentials exchange; it does not use a refresh token or run as a continuous background refresh. If the provider omits an expiry, Simple uses a five-minute lifetime for cache decisions. Cache lifetime is capped at six hours. Editing a connection invalidates its cached token, including when you change its secret, scopes, or token endpoint. Deleting a connection invalidates its cache too. A request selecting a missing connection must fail rather than silently continue without the requested authentication.

Restrict Where Tokens Are Sent

Allowed origins match the exact HTTPS scheme, hostname, and port. For https://api.example.com:

Requests to https://api.example.com/orders and /customers may use the connection when the fetch explicitly selects it.
Requests to a different subdomain, lookalike hostname, non-default port, or an HTTP URL do not qualify.
Paths are not an access boundary: entering a URL with a path stores its origin. Each fetch must still explicitly choose the connection.

Only allow API origins you trust to receive the credential. An allowed origin is a destination restriction, not an instruction to include credentials. Token attachment requires an explicit connection selection on that fetch. Limit the token’s actual permissions with the provider’s scopes and service-account permissions.

How Credentials Are Stored and Protected

Managed OAuth Credentials

Encryption at rest: client secrets and cached access tokens use AES-256-GCM authenticated encryption.
Write-only secrets: the client secret is accepted when creating or updating a connection, but is excluded from connection read responses. Those responses also exclude access tokens.
Organization isolation: connection lookup and execution check organization ownership. Configuration read and write permissions control connection management.
Runtime separation: Simple performs token exchange and header attachment outside the Code Action execution environment. The managed client secret and token are not supplied to the Action as inputs or configuration values.
Safe test results: connection tests report success, token type, and expiry information rather than returning the access token. Provider response bodies and free-form OAuth error descriptions are omitted from token-exchange errors.

These protections cover Simple’s credential handling. The destination API receives the access token, so use trusted destinations and avoid endpoints that reflect request credentials in their responses.

API Keys and Other Configuration Secrets

For credentials you use directly, open Configuration Variables, add a named value, mark it sensitive with the lock control, and save it. Use names such as CRM_API_KEY or BASIC_AUTH so Actions can reference them without embedding values in source code. All configuration-variable values are encrypted at rest with AES-256-GCM. Marking a variable sensitive additionally omits its saved plaintext from configuration read responses. Variable names and descriptions remain visible, so keep secrets in the value field. Configuration edits record which variable names and fields changed without recording their values in the configuration audit event. An HTTP Action references a variable with {{ config.CRM_API_KEY }}. A Code Action reads it as config.CRM_API_KEY. Unlike managed OAuth credentials, these values are available to the Action at runtime. Do not print them, return them as outputs, or interpolate them into conversation prompts. Marking a value sensitive does not make arbitrary Action code safe to log it.

Rotate or Revoke Credentials

To rotate an OAuth client secret, edit the connection and enter the replacement secret. Leaving that field empty preserves the stored secret. Saving the replacement invalidates the cached token so a subsequent execution exchanges the new credentials. For an API key, replace the sensitive configuration variable’s value. Keep the same name to preserve Action references. Remove unused connections and variables, and revoke old credentials with the provider. Deleting a connection in Simple does not revoke a token that the provider has already issued.

Test Authentication

First test the OAuth connection to confirm the credentials can obtain a token. Then run the Action’s test panel to confirm that the selected connection, allowed origin, provider permissions, and API request work together. A successful token test alone does not prove access to a particular API endpoint.

Symptom	What to check
Token endpoint rejects the connection	Client ID, replacement secret, Basic versus form-body authentication, scopes, and provider-specific settings.
Token test passes, API returns `401` or `403`	The fetch explicitly selects the intended connection, the origin is allowed, and the token has the API’s required audience and permissions.
Action reports a missing connection	Select an existing connection from the same organization on the affected fetch.
Token endpoint is unavailable	Check the provider’s availability and HTTPS token URL, then retry the test.

API Keys and Bearer Tokens

Use the header name and format required by the destination API. Common HTTP Action configurations are:

Header	Value template
`Authorization`	`Bearer {{ config.API_KEY }}`
`X-API-Key`	`{{ config.API_KEY }}`
`api-key`	`{{ config.API_KEY }}`

Choose the matching header for your provider; you do not need to send all three. A Code Action can set the same headers with fetch:

import { defineAction } from '@simple-ai-lab/sdk';

export default defineAction(async ({ config }) => {
  const response = await fetch('https://api.example.com/account', {
    headers: { Authorization: `Bearer ${config.API_KEY}` },
  });

  if (!response.ok) {
    throw new Error(`Account lookup failed with status ${response.status}`);
  }

  const account = await response.json();
  return { account };
});

If the provider requires a key in a query parameter or request body, use that location instead. Prefer headers when the provider supports them, and use HTTPS.

Mutual TLS (mTLS)

mTLS authenticates the client with a certificate and its corresponding private key during the TLS connection. It can also be used with OAuth, as described in OAuth mutual TLS. Actions currently do not expose customer-provided client certificates or private keys for outbound requests. Adding a certificate to an HTTP header or configuration variable does not enable mTLS. To reach an API that requires mTLS, have the Action call an HTTPS endpoint in your own middleware. Authenticate that request with a supported method, such as an API key, and configure your middleware to present the client certificate when it calls the destination API. Certificate provisioning, renewal, and private-key storage belong in that middleware.

Other Authentication Methods

Method	How to use it with Actions
HTTP Basic	Store the Base64-encoded `username:password` value in a configuration variable, then set `Authorization` to `Basic {{ config.BASIC_AUTH }}`. Base64 is encoding, not encryption; use HTTPS.
JWT bearer tokens	Send an existing JWT in the provider’s required header, commonly `Authorization: Bearer ...`. If the provider requires you to issue or exchange a signed JWT, implement that step in code or middleware and manage token expiry.
HMAC or signed requests	Use a Code Action to generate the provider’s required signature, timestamp, and headers for each request. Use middleware if the signing flow requires libraries or runtime features unavailable in Code Actions.
Session cookies	A Code Action can explicitly send a provider-issued cookie in a `Cookie` header. Your integration must handle login, renewal, and cookie storage; there is no persistent browser session between executions.
Custom headers	Add the provider’s required header names and reference their values from configuration variables. This can include a combination of credentials and account identifiers.
No authentication	Omit authentication headers for public endpoints that do not require credentials.

For calls to Simple AI itself, use the handler’s client: it is already authenticated for your organization. External services still require their own credentials.

Get Started

Core Concepts

Channels

Inbox

Campaigns

Journeys

Post-Call Intelligence

Agent Capabilities

Authentication

Integrations

CCaaS Integrations

SDK

Help Center

Authenticate Actions and Store Credentials Securely

Choose an Authentication Method

Managed OAuth Connections

Create a Connection

Choose Authentication on Each Fetch

Example: Choose an OAuth Connection in Code

How Tokens Are Obtained and Renewed

Restrict Where Tokens Are Sent

How Credentials Are Stored and Protected

Managed OAuth Credentials

API Keys and Other Configuration Secrets

Rotate or Revoke Credentials

Test Authentication

API Keys and Bearer Tokens

Mutual TLS (mTLS)

Other Authentication Methods

​Choose an Authentication Method

​Managed OAuth Connections

​Create a Connection

​Choose Authentication on Each Fetch

​Example: Choose an OAuth Connection in Code

​How Tokens Are Obtained and Renewed

​Restrict Where Tokens Are Sent

​How Credentials Are Stored and Protected

​Managed OAuth Credentials

​API Keys and Other Configuration Secrets

​Rotate or Revoke Credentials

​Test Authentication

​API Keys and Bearer Tokens

​Mutual TLS (mTLS)

​Other Authentication Methods

Choose an Authentication Method

Managed OAuth Connections

Create a Connection

Choose Authentication on Each Fetch

Example: Choose an OAuth Connection in Code

How Tokens Are Obtained and Renewed

Restrict Where Tokens Are Sent

How Credentials Are Stored and Protected

Managed OAuth Credentials

API Keys and Other Configuration Secrets

Rotate or Revoke Credentials

Test Authentication

API Keys and Bearer Tokens

Mutual TLS (mTLS)

Other Authentication Methods