This article is auto-synced from its in-app version in Tai.
An agent can be reached from your own server, from a signed-in user in TripBuilder or the Workbench, and, in future releases, from other kinds of callers. This page explains each way in: how it works, what it protects against, and what it does not.
When you'd use this
Use this page when you connect an integration or an embedded chat to an agent and want to know which method fits what the agent can reach. For example, an agent that reads traveller data should not be reachable with a credential that anyone can copy from a web page, while a public FAQ agent has less to protect.
Steps
Decide what is connecting: your own server, a signed-in TripBuilder user, a person working in the Workbench, or something else.
Find it in the table below and read that method's section. Methods marked Coming soon are not available to your company yet.
Set the method up with its guide: API keys for API keys and OAuth clients, the Agent REST API for tokens and calls, TripBuilder for signed-in TripBuilder users, Single sign-on for the Workbench.
Check the agent itself. On the REST API channel, each agent lists the methods it accepts under Configuration → Channels → Accepted authentication; other channels accept any caller that has access to the agent (Agent access).
Which one to choose
What is connecting | Method | Availability |
Your server, a simple integration with a fixed outgoing IP address | API key on your server | Available |
Your server, with standard OAuth libraries or short-lived tokens | OAuth 2.0 client credentials with client secret | Available |
Your server, an agent that reads sensitive data | OAuth 2.0 client credentials with key pair | Coming soon |
Signed-in users in TripBuilder | TripBuilder signed-in users | Available |
Users who sign in to your own website or app | Signed-in users of your own system | Coming soon |
Public visitors of your website | Website key for public visitors | Coming soon |
People working in the Workbench | Workbench users | Available |
Every method calls the same endpoints, such as POST /api/v1/agents/invoke, and names the agent in the request body; only how the caller proves who it is differs. The examples below call an agent through the Agent REST API; replace your-agent-id with the agent's ID and params with what its contract expects.
API key on your server
How it works. The integration sends the key in the X-API-Key header on every call. TAI checks the key, its IP addresses, its agents, channels and permissions, and its expiry.
Protects against. Calls from networks that are not on the key's IP list. Use beyond the key's agents and permissions. Continued use after revocation, which takes effect within about a minute.
Does not protect against. A leaked key used from an allowed network, or from anywhere if no IP list is set. The key travels with every request and can end up in logs and proxies. It says nothing about the end user.
Use it for. Simple server integrations with a fixed outgoing IP address. Always set Allowed IPs on the key.
Example. Create an API key under Settings → API Keys (type API key) and send it on every call:
curl https://taitravel.app/api/v1/agents/invoke \
-H "X-API-Key: $TAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent": "your-agent-id", "params": {"destination": "PT"}}'
OAuth 2.0 client credentials with client secret
How it works. You create an OAuth client under Settings → API Keys (type OAuth client, not API key). It has a client ID and client secrets, and no key value. Your backend sends the client ID and a client secret to TAI's token endpoint and receives a token valid for 15 minutes, which it sends as Authorization: Bearer. TAI re-checks the client on every call. It works with standard OAuth libraries.
Token renewal. There is no refresh token: the client simply requests a new token with its client secret. Standard OAuth client libraries (for example Spring Security, Authlib, requests-oauthlib and .NET) do this automatically: they cache the token and fetch a new one shortly before expires_in runs out. A request started with a valid token completes even if the token expires meanwhile.
Protects against. Exposure of the secret in transit and in logs: the secret goes only to the token endpoint, and only rarely. A leaked token expires within 15 minutes and stops within about a minute when the client or the client secret is revoked. A token can carry fewer permissions than its client.
Does not protect against. A leaked client secret: whoever has it can request tokens, unless the client's IP list blocks them. The secret sits in the integration's configuration and can be copied.
Use it for. Server integrations that expect OAuth, or that want short-lived tokens. To accept tokens only, untick API key under Accepted authentication on the agent.
Example. Create an OAuth client under Settings → API Keys (type OAuth client) and store its client ID and client secret. First get a token with them:
curl https://taitravel.app/api/v1/oauth/token \
-u "$TAI_CLIENT_ID:$TAI_CLIENT_SECRET" \
-d grant_type=client_credentials
# → {"access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 900, ...}
Then call the agent with the token, until it expires:
curl https://taitravel.app/api/v1/agents/invoke \
-H "Authorization: Bearer $TAI_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent": "your-agent-id", "params": {"destination": "PT"}}'
The API key value is not used here: an OAuth client has none.
OAuth 2.0 client credentials with key pair
Coming soon. This feature isn't available to your company yet.
How it works. The integration keeps a private key and registers the public key with TAI. For each token request it signs a short-lived assertion. TAI verifies it with the public key and issues a 15-minute token. Tokens are renewed the same way as with a client secret.
Protects against. Theft of a secret: TAI stores no secret, and the private key can be non-exportable in a key management service or hardware module, so it cannot be copied out of a configuration file. Replay of captured requests: assertions are short-lived.
Does not protect against. A compromised integration server: it can still sign. It says nothing about the end user.
Use it for. Server integrations that touch sensitive data.
TripBuilder signed-in users
How it works. A user signs in to TripBuilder. TripBuilder issues a short-lived token for that user, and the chat embedded in your TripBuilder-based app sends it to TAI as a bearer token. TAI verifies the token and knows which TripBuilder user is calling.
Protects against. Long-lived credentials in the browser. Anonymous use: every call is tied to a real TripBuilder user, so chats and audit entries are per user.
Does not protect against. Weak sign-in on TripBuilder's side: TAI trusts TripBuilder to have authenticated the user.
Use it for. The TAI chat embedded in TripBuilder-based apps with signed-in users. Nezasa sets this up together with you; see TripBuilder.
Example. The embedded chat sends the token for you. To call an agent's REST API with it directly, the agent must accept TripBuilder FIT (Federated Identity Token); send the token TripBuilder issued for the user:
curl https://taitravel.app/api/v1/agents/invoke \
-H "Authorization: Bearer $TRIPBUILDER_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent": "your-agent-id", "params": {"destination": "PT"}}'
Signed-in users of your own system
Coming soon. This feature isn't available to your company yet.
How it works. Your own sign-in system signs a short-lived token for the signed-in user. TAI verifies the signature with the public key you registered and knows which user is calling.
Protects against. Long-lived credentials in the browser. Anonymous use: every call is tied to a real user, so chats, audit entries and data can be per user.
Does not protect against. Weak sign-in on your side: TAI trusts your system. Tokens issued for a technical account and handed to a browser: every visitor then acts as that account.
Use it for. Chat embedded in apps and portals where users sign in.
Website key for public visitors
Coming soon. This feature isn't available to your company yet.
How it works. The key is visible in the page. The chat SDK trades it for a short-lived visitor token. TAI checks the page's domain against the key's referers. A random visitor ID keeps each visitor's chats apart.
Protects against. Other sites embedding your chat in a normal browser. Simple bots. Runaway cost, through usage limits. Visitors seeing each other's chats.
Does not protect against. A script outside a browser that fakes the domain: the key is public by design. Anything the agent can answer is effectively public. TAI does not know who the visitor is.
Use it for. Public chat on public knowledge.
Workbench users
How it works. A user signs in to the TAI Workbench with a password or single sign-on and acts with their own role.
Protects against. Whatever TAI's sign-in enforces, such as password rules, two-factor authentication and single sign-on.
Does not protect against. Misuse by the user within their own permissions.
Use it for. Working in TAI and testing agents. Not for integrations.
Example. No command is needed: an agent's Test API tab in the Workbench calls its REST API with your own session.
Tips and limits
Match the method to what the agent can reach. An agent that reads bookings, traveller details or finance data should not be connected with a credential that can be copied from a web page or a configuration file. Until the key-pair method is available, restrict the key to your server's IP addresses and set an expiry.
Today the Chat UI SDK sends a bearer token that your app supplies: a TripBuilder user's token, or a Workbench session. It does not take an API key.
An API key or client secret is shown once, when you create it. If you lose it, create a new one and revoke the old one.
Revoking an API key, an OAuth client or a client secret takes effect within about a minute, including for tokens already issued.
Browsing this page is open to all users; creating API keys, OAuth clients and client secrets requires the Company Admin role.
Related