Token configuration

Overview

In some Actions, the API call you’re configuring may require authentication. In that scenario, you can add an authentication Token that is stored securely.

Securely storing authentication Tokens is crucial for maintaining the security and integrity of your data. Think of authentication Tokens like digital keys that grant access to specific functions and data within a system. If they fall into the wrong hands, it could lead to unauthorized access, much like a burglar entering your house with your lost keys.

To prevent unauthorized access and to keep your data and your end users’ data secure, a secure authentication system stores your Tokens.

Use cases

Token configuration is useful when your Actions need to authenticate with external systems.

Backend API access: Use static Tokens to authenticate server-to-server API calls for retrieving order status, account details, or inventory data.
Authenticated end user actions: Use customer login Tokens when end users need to sign in before performing sensitive actions like viewing account balances or making purchases.
Third-party integrations: Securely store API keys for external services like payment processors, CRM systems, or shipping providers.

Capabilities & configuration

Token configuration supports the following authentication types:

Static Tokens: Fixed authentication values for server-to-server API calls. Use when the Token remains constant across all sessions.
Customer login Tokens: Session-based Tokens generated when end users sign in. Use when Actions require authenticated end user identity.

Quick start

Add a static authentication Token in minutes.

To add a static Token:

Go to Config > AI AGENT > Actions, then click Manage tokens.

Click New token.

Enter a Name, select Static value, and enter the Value.

Click Save.

In your Action, type @ and select the Token to reference it.

For customer login Tokens and detailed options, see Store authentication Tokens.

Implementation & usage

Store and reference authentication Tokens to secure your API calls.

Store authentication Tokens

Depending on the API, the Token you need to securely store may be a static value shared across all sessions or it may be generated for each end user when they use a login service.

Static Tokens

Static Tokens establish server-to-server authentication. A static Token is a fixed, unchanging piece of authentication information that’s used to authorize access to an API. Because the Token is static, it remains constant and will only stop working if the account credentials change (for example, if the password expires).

To add a static Token:

On the Ada dashboard, go to Config > AI AGENT > Actions, then click Manage tokens.

The Tokens page opens.
From the Tokens page, click New token.

The Create Token dialog box appears.
Under Name, enter a name for the Token.
From the Retrieve token from dropdown, select Static value.
Under Value, enter the Token.
Click Save.

After you save the Token, if you open it again, a censored version of the Token displays for security reasons.

Customer login Tokens authenticate an end user’s identity. When end users want to access sensitive information, or perform sensitive actions like making purchases, you should authorize those end users by asking them to sign in to their account. Sign-in confirms the end user is the person they claim to be.

A customer login Token is a type of authentication Token that is generated when an end user logs into a system. This Token is used to authenticate the end user’s interactions with the system during their session.

To add a customer login Token:

On the Ada dashboard, go to Config > AI AGENT > Actions, then click Manage tokens.

The Tokens page opens.
From the Tokens page, click New token.

The Create Token dialog box appears.
Under Name, enter a name for the Token.
From the Retrieve token from dropdown, select Customer login.
From the Chat experience tab, set up the sign-in flow end users will experience:
1. Under Message, enter the message end users will see in the chat.
2. Under Link Label, enter the link text for end users to click on rich messaging channels. Otherwise, for channels that only support plain text, your AI Agent provides end users with a sign-in URL to click instead.
When an Action that’s configured with a customer login Token is triggered in chat, the end user is prompted to sign in to retrieve the Token needed to proceed with the request. This ensures that the end user’s session is authenticated and that their interactions with the system are secure.
From the Token setup tab, fill in the following fields:
- Token URI: The address that the AI Agent calls to receive a Token if the end user’s credentials are valid. This Token keeps an end user verified for a specified amount of time.
- Redirect URI: The address the end user is returned to after a successful authorization. It will be formatted as {bot_handle}.ada.support/api/oauth/{auth_integration_name}.
- Auth URI: The address that the AI Agent calls to authenticate the end user. It specifies where it needs to confirm the end user’s credentials.
- Client ID: The first half of identification credentials so the authorization client can recognize which application is making the call.
- Client Secret: The second half of identification credentials so the authorization provider can recognize which application is trying to authenticate. Along with Client ID, both of these differentiate different applications that use the same authentication provider.
- Scopes (Optional): If required, you can specify how much access this application is trying to authenticate. Along with Client ID, both of these differentiate different applications that use the same authentication provider.
- Certificate: An additional layer of security so the authorization provider can confirm who the client is. This is the equivalent of a security badge or sign in key.

If you upload a certificate file in the dashboard, Ada automatically appends the AI Agent’s handle to the end of the file name to specify where the certificate is from.

Proof Key Code Exchange (PKCE): PKCE is a security feature to prevent injection attacks, especially in cases where mobile apps are being authorized using OAuth. Not all OAuth implementations support PKCE, and Ada only supports the S256 code challenge method, so its usage may vary depending on the OAuth version and provider. If the authentication provider requires PKCE for security, enable this toggle.

Click Save.

The Token is now listed in the Authentication page.

Reference Tokens in Actions

Once you have securely added a Token, you can reference it when setting up an Action. To reference the Token in one or more Actions, type @ and start typing the name of the Token to insert it.

Action control: Configure API calls that your AI Agent can use to retrieve external data and include it in responses.