Tool Authentication

When a tool uses API delivery, Tavus needs to know how to authenticate to the endpoint it’s calling. Set auth.type on delivery.api to one of the values below. The credentials live in the tool config alongside the URL.

Type	Use when	Adds
`none`	Public API	nothing
`bearer`	Long-lived token	`Authorization: Bearer <token>`
`api_key` (header)	Custom-header API key	`<name>: <value>`
`api_key` (query)	Key in URL	`?<name>=<value>`
`basic`	Username + password	`Authorization: Basic <b64>`
`oauth2_client_credentials`	M2M OAuth	`Authorization: Bearer <auto-refreshed>`
`hmac`	Customer-controlled callback	`X-Tavus-Signature: <hex>`

`none` - public APIs

"auth": { "type": "none" }

No auth header or query is added.

`bearer` - Bearer token

Use when the API gives you a single long-lived token.

"auth": { "type": "bearer", "token": "sk_live_abc123..." }

Adds Authorization: Bearer sk_live_abc123... to the request.

`api_key` - API key in a header or query string

In a custom header

"auth": {
  "type": "api_key",
  "location": "header",
  "name": "X-API-Key",
  "value": "abc123..."
}

In the URL query string

"auth": {
  "type": "api_key",
  "location": "query",
  "name": "api_key",
  "value": "abc123..."
}

location defaults to header. The named header/query is added to every request.

`basic` - HTTP Basic auth

"auth": {
  "type": "basic",
  "username": "alice",
  "password": "s3cret"
}

Adds Authorization: Basic <base64(username:password)>.

`oauth2_client_credentials` - machine-to-machine OAuth 2.0

For APIs that issue short-lived tokens via the OAuth2 client_credentials grant. Tavus exchanges your credentials for an access token, caches it per worker, and refreshes it automatically as it nears expiry. If the API returns 401 (e.g. the token was revoked out-of-band), Tavus drops the cached token, fetches a fresh one with the same credentials, and retries the request once.

"auth": {
  "type": "oauth2_client_credentials",
  "token_url": "https://accounts.example.com/oauth2/token",
  "client_id": "abc123",
  "client_secret": "secret_xyz",
  "scope": "read:orders write:tickets"
}

Field	Required	Description
`token_url`	✅	HTTPS endpoint Tavus POSTs the `client_credentials` grant to. Validated the same way as the tool URL.
`client_id`	✅	Provided by the API.
`client_secret`	✅	Provided by the API.
`scope`	❌	OAuth scope string. Omit if the API doesn’t use scopes.

On the request itself Tavus adds Authorization: Bearer <auto-refreshed-token>. User-delegated OAuth (the “Log in with…” flow with per-end-user refresh tokens) is not supported.

`hmac` - signed Tavus-shape callback

HMAC (Hash-based Message Authentication Code) is a shared-secret signature: it proves the request was sent by someone who knows your secret and that the body was not altered in transit. For customer-controlled callback endpoints. Tavus signs the request body with HMAC-SHA256 and sends the hex digest in X-Tavus-Signature. The body uses the Tavus callback shape, not the templated/auto-routed shape from body_template or query auto-routing.

"auth": { "type": "hmac", "secret": "your_shared_secret" }

Use this when you control the receiving endpoint and want signature verification. For third-party APIs, use one of the other auth types instead. See Verifying API signatures for receiver-side code samples.

​none - public APIs

​bearer - Bearer token

​api_key - API key in a header or query string

​basic - HTTP Basic auth

​oauth2_client_credentials - machine-to-machine OAuth 2.0

​hmac - signed Tavus-shape callback