How to Authenticate Requests to the CloudTalk REST API

Every request you make to the CloudTalk API must be authenticated. CloudTalk uses HTTP Basic Authentication across the whole API, on every host — you supply an API Access Key ID as the username and an API Access Key Secret as the password. These credentials tie the request to a specific CloudTalk project, determining which account’s data the API reads and writes. This page walks you through generating your keys and including them correctly in every request.

Generate Your API Keys

Only Administrators can create API keys. If you don’t have administrator access to your CloudTalk account, ask your account admin to generate a key pair for you.

Open Account Settings

Log in to the CloudTalk Dashboard and navigate to Account → Settings in the left-hand sidebar, or go straight to https://dashboard.cloudtalk.io/menu/account/settings/API-keys.

Go to the API Keys Tab

Inside Settings, select the API Keys tab. You’ll see a list of any existing keys along with their creation dates and labels.

Create a New Key

Click Add API Key (or Generate New Key, depending on your dashboard version). Give the key a descriptive label — for example, CRM Integration or Data Pipeline — so you can identify it later.

Copy Your Credentials

CloudTalk displays your API Access Key ID and API Access Key Secret once, immediately after creation. Copy both values to a secure location (such as a secrets manager) before closing the dialog. The secret is not shown again.

Store your API Access Key Secret securely as soon as it’s generated. CloudTalk does not display the secret a second time. If you lose it, you must revoke the key and create a new one.

Authenticate a Request

Using cURL

Pass your credentials with the -u flag, which automatically encodes them as HTTP Basic Auth:

curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  -H "Accept: application/json" \
  https://my.cloudtalk.io/api/calls/index.json

Example with real-looking credentials:

curl -u ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An \
  -H "Accept: application/json" \
  https://my.cloudtalk.io/api/calls/index.json

Send Accept: application/json on every core API GET. A request without it may be rejected with a 404 or 406.

Using the Authorization Header Directly

For programmatic use, compute the Base64 encoding of KEY_ID:KEY_SECRET and pass it in the Authorization header:

Authorization: Basic base64(ACCESS_KEY_ID:ACCESS_KEY_SECRET)

For example, if your key ID is ABCDEFGHIJTESTKEY1 and your secret is X05Dg4c331c3h61An, the raw credential string is:

ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An

Base64-encoded, that becomes a value you include in the header:

Authorization: Basic QUJDREVGR0hJSlRFU1RLRVkxOlgwNURnNGMzMzFjM2g2MUFu

Most HTTP client libraries handle this encoding for you automatically when you pass a username and password — you rarely need to compute it by hand.

Code Examples

curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  -H "Accept: application/json" \
  https://my.cloudtalk.io/api/calls/index.json

import requests
import os

key_id     = os.environ["CLOUDTALK_KEY_ID"]
key_secret = os.environ["CLOUDTALK_KEY_SECRET"]

response = requests.get(
    "https://my.cloudtalk.io/api/calls/index.json",
    auth=(key_id, key_secret),
    headers={"Accept": "application/json"},
)

response.raise_for_status()
print(response.json())

import fetch from "node-fetch";

const keyId     = process.env.CLOUDTALK_KEY_ID;
const keySecret = process.env.CLOUDTALK_KEY_SECRET;

const credentials = Buffer.from(`${keyId}:${keySecret}`).toString("base64");

const response = await fetch("https://my.cloudtalk.io/api/calls/index.json", {
  headers: {
    "Authorization": `Basic ${credentials}`,
    "Accept": "application/json",
  },
});

if (!response.ok) {
  throw new Error(`CloudTalk API error: ${response.status}`);
}

const data = await response.json();
console.log(data);

HTTPS Requirement

The API only accepts connections over HTTPS. Any request sent over plain HTTP is rejected. All four base URLs enforce this:

https://my.cloudtalk.io/api/
https://api.cloudtalk.io/v1/
https://analytics-api.cloudtalk.io/api/
https://platform-api.cloudtalk.io/api/

Never send API credentials over plain HTTP. Always use https:// URLs to ensure your credentials are encrypted in transit.

Which Account Do My Credentials Target?

Your API Access Key ID and Secret are scoped to the CloudTalk project (account) they were created in. If your organization has multiple CloudTalk projects, you need separate key pairs for each one. The credentials you include in a request determine which project’s data is read or modified — there is no way to cross projects with a single credential pair.

401 Unauthorized

If your credentials are missing, incorrect, or revoked, the API returns an HTTP 401 response with the following body:

{
  "responseData": {
    "status": 401,
    "message": "Unauthorized"
  }
}

Common causes of a 401:

The Authorization header is missing entirely.
The key ID or secret contains a typo or extra whitespace.
The key has been revoked from the Dashboard.
You are using credentials created for a different CloudTalk project than the one holding the data you are requesting. Base URLs select an API service, not a project — the project is determined entirely by the credentials.

Security Best Practices

Keeping your API credentials safe protects your CloudTalk account from unauthorized access. Follow these guidelines:

Use Environment Variables

Never hard-code credentials in source code. Load them from environment variables or a secrets manager at runtime.

Keep Keys Out of Version Control

Add credential files to .gitignore. Audit your repository history if you suspect a key was committed.

Rotate Keys Periodically

Generate new key pairs on a regular schedule or immediately after any suspected exposure. Revoke old keys from the Dashboard once rotation is complete.

Use Separate Keys per Integration

Create a distinct key pair for each application or service that calls the API. This limits blast radius if one key is compromised and makes it easier to audit usage.

The Other API Hosts

A few resource groups live on dedicated hosts rather than my.cloudtalk.io/api: Call Flow Analytics on analytics-api.cloudtalk.io, CueCard on platform-api.cloudtalk.io, and Conversation Intelligence, VoiceAgent and the Dialer partner API on api.cloudtalk.io/v1 (see Base URLs). Your credentials work unchanged on all of them — only the host and the response shape differ:

curl --request GET \
  --url 'https://api.cloudtalk.io/v1/dialer/campaigns?limit=10' \
  --user KEY_ID:KEY_SECRET

On api.cloudtalk.io/v1, a missing or invalid credential returns a 401 from the authentication layer in front of the host — identically for the AI, VoiceAgent and Dialer endpoints — with a { "code": "UNAUTHORIZED", "message": "..." } body instead of the core API’s responseData envelope.

Next Steps

With authentication in place, you’re ready to make your first live API call.

Quickstart

List calls and trigger an outbound call in under 5 minutes.

API Reference

Browse every endpoint, see request/response schemas, and try calls in the live playground.

Getting Started

API Concepts

Changelog

How to Authenticate Requests to the CloudTalk REST API

Generate Your API Keys

Authenticate a Request

Using cURL

Using the Authorization Header Directly

Code Examples

HTTPS Requirement

Which Account Do My Credentials Target?

401 Unauthorized

Security Best Practices

Use Environment Variables

Keep Keys Out of Version Control

Rotate Keys Periodically

Use Separate Keys per Integration

The Other API Hosts

Next Steps

Quickstart

API Reference

​Generate Your API Keys

​Authenticate a Request

​Using cURL

​Using the Authorization Header Directly

​Code Examples

​HTTPS Requirement

​Which Account Do My Credentials Target?

​401 Unauthorized

​Security Best Practices

Use Environment Variables

Keep Keys Out of Version Control

Rotate Keys Periodically

Use Separate Keys per Integration

​The Other API Hosts

​Next Steps

Quickstart

API Reference

Generate Your API Keys

Authenticate a Request

Using cURL

Using the Authorization Header Directly

Code Examples

HTTPS Requirement

Which Account Do My Credentials Target?

401 Unauthorized

Security Best Practices

The Other API Hosts

Next Steps