> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Authentication

> How Tavus authenticates to your endpoint when a tool is delivered via an API call.

When a tool uses [API delivery](/sections/conversational-video-interface/pal/llm-tool-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

```json theme={null}
"auth": { "type": "none" }
```

No auth header or query is added.

## `bearer` - Bearer token

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

```json theme={null}
"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

```json In a custom header theme={null}
"auth": {
  "type": "api_key",
  "location": "header",
  "name": "X-API-Key",
  "value": "abc123..."
}
```

```json In the URL query string theme={null}
"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

```json theme={null}
"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.

```json theme={null}
"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](/sections/conversational-video-interface/pal/llm-tool-delivery#tavus-callback-shape), not the templated/auto-routed shape from `body_template` or query auto-routing.

```json theme={null}
"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](/sections/conversational-video-interface/pal/llm-tool-delivery#verifying-api-signatures) for receiver-side code samples.