Auth Profiles

Auth Profiles let you define authentication credentials once and reuse them across Pre-conversation, In-conversation, and Post-conversation API requests. Instead of hardcoding tokens or passwords into every action, create a profile in one place and select it wherever you need it.

​

Overview

• Centrally managed — update a credential in one profile and every action that references it picks up the change automatically.
• Secure storage — sensitive fields (tokens, passwords, client secrets, API key values, and mTLS certificates, private keys and passphrases) are encrypted at rest.
• Four authentication types, plus mTLS — Bearer Token, API Key, Basic Auth, and OAuth 2.0 (Client Credentials), with optional mTLS (client certificate) on top of any of them.

​

Authentication Types

Under Application Authentication, choose how the platform authenticates each request: Bearer Token, API Key, Basic Auth or OAuth 2.0. None is also available, for a profile that only uses mTLS. You can then add certificate-based Transport Authentication on top — see mTLS (Client Certificate).

​

Bearer Token

Send a static token in the Authorization header of every request. Best for APIs that issue long-lived tokens or personal access tokens (e.g. OpenAI, HubSpot private apps).

​

API Key

Attach one or more key-value pairs to the request via header, query string, or request body. Use this type when your API expects a named key such as x-api-key, api_key, or similar.

​

Basic Auth

Authenticate with a username and password, encoded as a standard HTTP Basic credential. The platform sends Authorization: Basic base64(username:password) with each request.

​

OAuth 2.0 — Client Credentials

For machine-to-machine integrations that use the OAuth 2.0 Client Credentials grant. The platform automatically fetches (and refreshes) an access token before each request. Test your credentials. While OAuth 2.0 is selected, a Test button appears at the bottom left of the drawer. It stays disabled until Token Endpoint, Client ID and Client Secret are filled in. Click it to request a token from your token endpoint. An OAuth Token Response dialog shows the Status, the Access Token and the Full Response, or the error if the request fails. You can run the test before you save the profile.

​

mTLS (Client Certificate)

Some APIs require your side of the connection to prove its identity with a client certificate (mutual TLS), either in addition to a credential in the request or on its own. mTLS is optional and is set separately from the authentication types above. Under Transport Authentication, tick Enable mTLS (Client Cert) to add it to a profile. It works with any Application Authentication type. For a profile that uses only a certificate, choose None under Application Authentication. Studio won’t save the profile unless the certificate and the private key are in PEM format. The platform presents the certificate on every API request that uses the profile, and still verifies the API server’s own certificate. In the profile list, a profile that uses mTLS shows a label such as mTLS or mTLS + OAuth 2.0.

​

Managing Profiles

Open Manage → Auth Profiles to view, create, edit, search, and delete profiles. Each profile in the list shows its name, its authentication type (for example Bearer Token or mTLS + OAuth 2.0) and the date it was created. Use Search profiles by name to find one.

​

Create a Profile

1. Click New Profile. The Create Auth Profile drawer opens.
2. Enter a Profile Name (e.g. “Salesforce Production”).
3. Under Application Authentication, choose Bearer Token, API Key, Basic Auth or OAuth 2.0. A new profile starts on Bearer Token. Choose None only for a profile that uses mTLS alone.
4. Fill in the required fields for the selected type.
5. Optional: under Transport Authentication, tick Enable mTLS (Client Cert) and fill in the certificate fields.
6. Click Create.

​

Edit a Profile

Click the Edit icon next to any profile to update its name, type, or credentials. The drawer is titled Edit Auth Profile, and its button is Save Changes. Secrets you’ve already saved appear masked as ********. Leave a masked value as it is to keep what’s stored, or type a new value to replace it.

​

Delete a Profile

Click the Delete icon next to any profile. The platform will check whether the profile is currently in use:

• Not in use — a confirmation dialog appears and you can proceed (click Delete Profile to confirm).
• In use — a dialog headed Authentication Profile In Use shows which Pre-conversation Actions, Post-conversation Actions, and Flow Nodes reference the profile, with the agent each one belongs to. Remove the profile from those locations first, then retry deletion.

If the delete request itself is refused — because a reference exists that the pre-delete summary could not see, such as one in an agent’s published version — Studio opens a dialog headed “Can’t Delete Profile In Use”. It explains that the profile is in use by one or more agents and can’t be deleted, and lists every agent that still references it. Each agent is tagged Published, Draft, or both, to show whether the reference is in its published version, in a draft, or in both. An Action Required panel tells you what to do: point those agents at a different profile, or remove the authentication requirement, then try again. The dialog is deliberately read-only; the only button is Close and there is no force-delete.

​

Using a Profile in Actions

Any API Request configuration — in Pre-conversation, In-conversation, or Post-conversation actions — has an Auth tab, alongside Params, Headers and Body. To use a profile:

1. Open the request’s Auth tab.
2. Tick Use Auth Profile.
3. Choose a profile under Auth Profile. Type in Search profiles… to filter the list.
4. The platform injects the appropriate credentials at request time.

While Use Auth Profile is ticked, the request uses the profile’s stored credentials instead of any inline authentication settings. If you leave Use Auth Profile unticked, the Auth tab shows Configure Authentication instead. It has the same options as a profile — Application Authentication (including None) and the mTLS settings — but they apply to that one request, and nothing is saved as a profile. For OAuth 2.0, a Test button sits beside the heading. When several actions need the same credentials, use a profile so you only maintain them once.

​

Best Practices

• One profile per external service — name profiles after the service they authenticate against (e.g. “Zendesk API”, “Twilio Prod”).
• Rotate credentials in one place — when a token or secret expires, update the profile and all referencing actions inherit the new value.
• Use OAuth 2.0 when available — the automatic token refresh reduces manual maintenance compared to static bearer tokens.
• Audit usage before deletion — the usage summary shows which actions and flow nodes to switch to a different profile first. A profile an agent still uses can’t be deleted.