Skip to main content

​
Authentication

All requests to the Talkover API require authentication using environment tokens. This guide explains how to get your token and use it in API requests.

​
Getting Your Environment Token

​
Step 1: Access Your Dashboard

  1. Log in to your Talkover account at app.talkover.ai
  2. Navigate to Account in the left sidebar
  3. Click on “Environments”

​
Step 2: Copy Your Token

Your environment tokens will be displayed in the Environments section. Each environment has its own token that starts with talq_ followed by a long string of characters.
Example token format: talq_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
Security Notice: Your environment token is like a password. Never share it publicly, commit it to version control, or include it in client-side code.

​
Using Your Token in API Requests

​
HTTP headers

Include your token in the Authorization header of all API requests: 
Authorization: Bearer talq_your_environment_token_here

​
Example cURL Request

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890"
  }'

​
Example JavaScript Request

const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+1234567890'
  })
});

​
Example Python Request

import requests

headers = {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
}

data = {
    'to': '+1234567890'
}

response = requests.post(
    'https://app.talkover.ai/api/v1/agents/agent_123456/call',
    headers=headers,
    json=data
)

​
Environment Variables

For security, store your token in environment variables:

​
Bash/Linux/macOS

export TALKOVER_TOKEN="talq_your_environment_token_here"

​
Windows (Command Prompt)

set TALKOVER_TOKEN=talq_your_environment_token_here

​
Windows (PowerShell)

$env:TALKOVER_TOKEN="talq_your_environment_token_here"

​
Using Environment Variables in Code

// JavaScript
const token = process.env.TALKOVER_TOKEN;

# Python
import os
token = os.environ.get('TALKOVER_TOKEN')

// PHP
$token = $_ENV['TALKOVER_TOKEN'];

​
Token Security Best practices

​
Do

  • Store tokens in environment variables
  • Use secure secret management services
  • Rotate tokens regularly
  • Use different tokens for different environments (dev, staging, prod)

​
Don’t

  • Never commit tokens to version control
  • Don’t share tokens in public repositories
  • Avoid hardcoding tokens in your application
  • Don’t include tokens in client-side code

​
Token Management

​
Regenerating Your Token

If your token is compromised or you need to rotate it:
  1. Go to Account → Environments in your dashboard
  2. Click “Regenerate Token”
  3. Copy the new token
  4. Update your applications with the new token
  5. Delete the old token from your code

​
Token Expiration

Environment tokens don’t expire automatically, but you can regenerate them at any time for security purposes.

​
Troubleshooting

​
Common Authentication Errors

Error CodeDescriptionSolution
401 UnauthorizedInvalid or missing tokenCheck your token is correct and included in the Authorization header
403 ForbiddenToken doesn’t have required permissionsContact support if you believe this is an error
429 Too Many RequestsRate limit exceededWait before making more requests

​
Testing Your Token

You can test if your token is working by making a simple request: 
curl -H "Authorization: Bearer talq_your_environment_token_here" \
  https://app.talkover.ai/api/v1/agents
If successful, you should receive a response with your agents list (or an empty array if you don’t have any agents yet).

​
Next Steps