do.dev

Authentication

How to authenticate your Talk API requests

All Talk API endpoints require authentication using a unified do.dev API key.

Getting an API Key

  1. Sign up at do.dev
  2. Go to your Dashboard
  3. Create an API key with the talk service enabled
  4. Copy and securely store your do_live_* key

Authentication Methods

Pass your API key as a Bearer token in the Authorization header:

curl -X POST "https://api.do.dev/v1/talk/speech" \
  -H "Authorization: Bearer do_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "aria"}'

Option 2: X-API-Key Header

Pass your API key in the X-API-Key header:

curl -X POST "https://api.do.dev/v1/talk/speech" \
  -H "X-API-Key: do_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "aria"}'

Which method should I use?

We recommend using Bearer token or X-API-Key header as they keep your API key out of server logs and browser history.

Scopes

Talk API endpoints require specific scopes on your API key:

EndpointRequired Scope
POST /v1/talk/speechtalk:speech
GET /v1/talk/voicestalk:voices
GET /v1/talk/formatstalk:formats

Use talk:* to grant access to all Talk endpoints.

Authentication Errors

Missing API Key

If no API key is provided, you'll receive a 401 Unauthorized response:

{
  "error": "API key required. Use Authorization: Bearer <key> or X-API-Key header."
}

Invalid API Key

If the API key is invalid or inactive:

{
  "error": "Invalid API key"
}

Insufficient Scope

If the API key lacks the required scope:

{
  "error": "Insufficient scope. Required: talk:speech"
}

Service Not Enabled

If the API key doesn't have the talk service enabled:

{
  "error": "API key does not have access to the talk service"
}

Security Best Practices

  1. Never expose your API key in client-side code, public repositories, or logs
  2. Use environment variables to store API keys in your applications
  3. Rotate keys regularly if you suspect they may have been compromised
  4. Use separate keys for development and production environments
  5. Use minimal scopes — only grant the scopes each key needs

Example: Using Environment Variables

Node.js

const apiKey = process.env.DO_API_KEY;

const response = await fetch("https://api.do.dev/v1/talk/speech", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Hello world",
    voice: "aria"
  })
});

Python

import os
import requests

api_key = os.environ.get("DO_API_KEY")

response = requests.post(
    "https://api.do.dev/v1/talk/speech",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={"text": "Hello world", "voice": "aria"}
)