Tool Authentication

Most external APIs require authentication. OmniBots supports multiple authentication methods that you configure directly in the tool's HTTP headers. Credentials are stored securely using environment variables, with secrets encrypted at rest.

Authentication Methods

No Authentication

Some APIs are public and do not require credentials. In this case, leave the Authorization header empty. You may still need to set Content-Type or other non-auth headers.

API Key

Pass an API key as a header value or query parameter.

Header-based (most common):

X-API-Key: {{env.MY_SERVICE_API_KEY}}

Query parameter-based (append to URL):

{{env.BACKEND_API}}/data?api_key={{env.MY_SERVICE_API_KEY}}

Bearer Token

Pass a static token in the Authorization header:

Authorization: Bearer {{env.MY_SERVICE_TOKEN}}

For tokens obtained through user SSO authentication (where the end user authenticates during the conversation), use the auth_token variable instead:

Authorization: Bearer {{auth_token.access_token}}

SSO vs Static Tokens

Use {{env.SERVICE_TOKEN}} for service-to-service authentication where the token represents your application. Use {{auth_token.access_token}} when the API call must be made on behalf of the authenticated end user.

Basic Authentication

For APIs using HTTP Basic Auth, encode your credentials in the Authorization header:

Authorization: Basic {{env.MY_SERVICE_BASIC_AUTH}}

Store the Base64-encoded username:password string as a secret environment variable.

OAuth2 -- Client Credentials

For service-to-service OAuth2 flows, you typically obtain a token from the provider's token endpoint and store it as an environment variable. OmniBots does not currently manage OAuth2 token refresh automatically, so you have two options:

1. Long-lived token -- Store a long-lived access token as {{env.OAUTH_TOKEN}} and refresh it manually when it expires.
2. Composite tool -- Create a tool that calls the token endpoint first, then use the returned token in a second API call using a composite action.

OAuth2 -- Authorization Code

For APIs that require end-user authorization (e.g., accessing a user's Google Drive), use the platform's SSO integration to handle the OAuth2 authorization code flow. The resulting access token is available as {{auth_token.access_token}} in your tool configuration.

Configure the SSO provider in Settings > Authentication > SSO, and use the Require Authentication system tool in your flow to trigger the login before calling the tool.

Using Environment Variables for Secrets

All credentials should be stored as environment variables rather than hardcoded in the tool configuration. This keeps secrets out of your tool definitions and lets you change credentials without editing every tool.

Setting Environment Variables

1. Navigate to Settings > Tool Environment.
2. Click Add Variable.
3. Enter a name (e.g., API_KEY) and value.
4. Toggle Secret for sensitive values like API keys, tokens, and passwords.
5. Click Save.

imageTool Environment settings page showing a list of environment variables with Name, Value (masked for secrets), and Secret toggle columns, plus Add Variable button

Environment variables configuration in Settings

Secret vs Non-Secret Variables

Type	Stored As	Displayed As	Use For
Regular	Plain text	Full value visible	Base URLs, non-sensitive config
Secret	Encrypted	******** (masked)	API keys, tokens, passwords

WARNING

Secret values cannot be read back after saving. If you need to update a secret, you must enter the new value. The old value cannot be retrieved.

Referencing Environment Variables

Use the {{env.VARIABLE_NAME}} syntax anywhere in a tool's URL, headers, or body:

URL:     {{env.BACKEND_API}}/accounts/{{param.id}}
Headers: X-API-Key: {{env.API_KEY}}
         Authorization: Bearer {{env.SERVICE_TOKEN}}

How Credentials Are Stored

OmniBots takes credential security seriously:

• Encryption at rest -- Secret environment variables are encrypted using KMS before being written to the database.
• Tenant isolation -- Environment variables are scoped to your tenant. No other tenant can access them.
• Masked display -- Secret values are never returned by the API or shown in the UI after saving.
• Audit logging -- All changes to environment variables are recorded in the audit log.
• No logging of secrets -- Secret values are excluded from request logs and conversation transcripts.

Choosing the Right Method

Scenario	Recommended Method
Third-party API with a static key	API Key via {{env.API_KEY}}
Internal service with a service account	Bearer Token via {{env.SERVICE_TOKEN}}
API requiring user identity (e.g., banking)	SSO + {{auth_token.access_token}}
Legacy system with username/password	Basic Auth via {{env.BASIC_AUTH}}
OAuth2 provider with client credentials	Store token in {{env.OAUTH_TOKEN}}