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

# How to Authenticate Requests to the CloudTalk REST API

> The CloudTalk API uses HTTP Basic Auth with an API Access Key ID and Secret on every host. Learn how to generate keys, pass credentials, and secure your requests.

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.

<Steps>
  <Step title="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](https://dashboard.cloudtalk.io/menu/account/settings/API-keys).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.**
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Authenticate a Request

### Using cURL

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

```bash theme={"system"}
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:**

```bash theme={"system"}
curl -u ABCDEFGHIJTESTKEY1:X05Dg4c331c3h61An \
  -H "Accept: application/json" \
  https://my.cloudtalk.io/api/calls/index.json
```

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

### 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:

```http theme={"system"}
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

<CodeGroup>
  ```bash curl theme={"system"}
  curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
    -H "Accept: application/json" \
    https://my.cloudtalk.io/api/calls/index.json
  ```

  ```python Python theme={"system"}
  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())
  ```

  ```javascript Node.js theme={"system"}
  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);
  ```
</CodeGroup>

## 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/`

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

## 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:

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

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="shield-halved">
    Never hard-code credentials in source code. Load them from environment variables or a secrets manager at runtime.
  </Card>

  <Card title="Keep Keys Out of Version Control" icon="code-branch">
    Add credential files to `.gitignore`. Audit your repository history if you suspect a key was committed.
  </Card>

  <Card title="Rotate Keys Periodically" icon="rotate">
    Generate new key pairs on a regular schedule or immediately after any suspected exposure. Revoke old keys from the Dashboard once rotation is complete.
  </Card>

  <Card title="Use Separate Keys per Integration" icon="key">
    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.
  </Card>
</CardGroup>

## 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](/guides/introduction#base-urls)). Your credentials work unchanged on all of them — only the host and the response shape differ:

```bash theme={"system"}
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.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    List calls and trigger an outbound call in under 5 minutes.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Browse every endpoint, see request/response schemas, and try calls in the live playground.
  </Card>
</CardGroup>


## Related topics

- [CloudTalk REST API: Call Center Automation Platform](/guides/introduction.md)
- [How to Paginate CloudTalk API Collection Responses](/guides/pagination.md)
- [CloudTalk REST API v1.7 — Complete Developer Reference](/api-reference/overview.md)