Skip to main content

Authenticate your AI Agent's API calls using tokens

Understand how authentication works in Ada​

In some Actions, the API call you're configuring may require authentication. In that scenario, you can add an authentication token that Ada stores 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 customers' data secure, Ada uses a secure authentication system to store your tokens.

Securely store authentication tokens in Ada​

Depending on the API, the token you need to securely store may be a static value shared by all customers or it may be generated for each customer when they use a login service.

Establish server-to-server authentication with static tokens​

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).

  1. On the Ada dashboard, go to Platform > Tokens. The Tokens page opens.

  2. From the Tokens page, click New token. The Create Token dialog box appears.

  3. Under Name, enter a name for the token.

  4. From the Retrieve token from... dropdown, select Static value.

  5. Under Value, enter the token.

  6. Click Save. After you save the token, if you open it again, a censored version of the token will display for security reasons.

Authenticate a customer's identity with customer login tokens​

When customers want to access sensitive information, or perform sensitive actions like making purchases, you should authorize those customers by asking them to sign in to their account. Sign-in confirms the chatter is the person they claim to be. This authentication process is done using customer login tokens.

A customer login token is a type of authentication token that is generated when a customer logs into a system. This token is used to authenticate the customer's interactions with the system during their session.

  1. On the Ada dashboard, go to Platform > Tokens. The Tokens page opens.

  2. From the Tokens page, click New token. The Create Token dialog box appears.

  3. Under Name, enter a name for the token.

  4. From the Retrieve token from... dropdown, select Customer login.

  5. From the Chat experience tab, set up the sign-in flow your customers will experience:

    1. Under Message, enter the message your customers will see in the chat.

    2. Under Link Label, enter the link text for customers to click on rich messaging channels. Otherwise, for channels that only support plain text, your AI Agent will provide customers with a sign-in URL to click instead.

    note

    When an Action that's configured with a customer login token is triggered in chat, the customer is prompted to sign-in in order to retrieve the token needed to proceed with the request. This ensures that the customer's session is authenticated and that their interactions with the system are secure.

  6. From the Token setup tab, fill in the following fields:

    • Token URI: The address that the bot calls to receive a token if the chatter’s credentials are valid. This token keeps a chatter verified for a specified amount of time.

    • Redirect URI: The address the chatter 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 bot calls to authenticate the chatter. It specifies where it needs to confirm the chatter’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 authentication allows. This adds an extra layer of security to limit access in case the token is compromised.

    • 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.

      note

      If you upload a certificate file in the dashboard, Ada will automatically append the bot’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, turn this setting on.

  7. Click Save. The token is now listed in the Authentication page.

Reference a secure token in an Action​

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

Have any questions? Contact your Ada team—or email us at .