Authorization Options

Overview

Server tools authenticate against your external API using a credential you store with POST /secrets. Credentials are encrypted at rest and never appear in the tool object or any API response — the tool definition holds only a reference (secret_id). Four credential types are supported: bearer, API key, basic, and OAuth2.

Client tools do not use this flow. They run in the user's browser; whatever auth the browser already has (cookies, session storage) is available to the handler directly.

You create the secret once and reference it from every tool that uses it. When the agent invokes the tool, the secret_id is resolved and the appropriate header is attached to the outbound request.

Authentication Types

Create a Secret

Bearer, API key, and basic secrets are created with POST /secrets. Each type has its own request shape; the response is the same — an id you reference from the tool. OAuth2 secrets follow a different path — see the OAuth2 section below.

Bearer

curl -X POST "https://api.d-id.com/secrets" \
  -H "Authorization: Basic <YOUR KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bearer",
    "provider": "Weather API",
    "token": "wk_live_abc123"
  }'

{
  "id": "sec_o0kaqea3v",
  "provider": "Weather API",
  "type": "bearer",
  "sanitized_secret": "•••••••••",
  "created_at": "2026-05-20T12:00:00.000Z"
}

API Key

curl -X POST "https://api.d-id.com/secrets" \
  -H "Authorization: Basic <YOUR KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "api_key",
    "provider": "Storefront",
    "api_key": "sk_live_abc123",
    "header_name": "X-API-Key"
  }'

header_name is optional — omit it to send the key in the default X-API-Key header.

Basic

curl -X POST "https://api.d-id.com/secrets" \
  -H "Authorization: Basic <YOUR KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "basic",
    "provider": "Internal CRM",
    "username": "service-account",
    "password": "rotated-monthly"
  }'

OAuth2

OAuth2 secrets are created through D-ID Studio rather than the API. The authorization flow requires a user-facing redirect to the provider's consent screen, so Studio runs the dance for you: you supply the OAuth client details, Studio opens the provider's authorize page, and the resulting tokens are stored as a secret tied to your account.

Once the secret exists, treat it like any other — reference it from a tool's auth.secret_id field via the API. Access-token refresh happens automatically against the configured token_url; you do not need to re-authorize unless the refresh token itself is revoked.

Reference the Secret from a Tool

Once the secret exists, attach it to the tool with auth.secret_id.

curl -X POST "https://api.d-id.com/tools" \
  -H "Authorization: Basic <YOUR KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_current_weather",
    "description": "Get current weather for a city",
    "provider": "Weather API",
    "schema": { "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } },
    "config": { "type": "server", "url": "https://api.weatherapi.example.com/current", "method": "GET" },
    "auth": { "secret_id": "sec_o0kaqea3v" }
  }'

The same secret_id can be referenced from any number of tools. Rotating the credential happens in one place — PUT /secrets/{id} — and every tool that references it picks up the new value on the next call.

FAQ