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

# API authentication

> Create, scope, and revoke API keys, and authenticate Tars API requests with Bearer tokens.

export const api = {
  env: "production",
  defaultRegion: "us",
  defaultBase: "https://us.api.hellotars.com",
  regions: [{
    id: "us",
    label: "United States",
    flag: "🇺🇸",
    base: "https://us.api.hellotars.com"
  }, {
    id: "eu",
    label: "European Union",
    flag: "🇪🇺",
    base: "https://eu.api.hellotars.com"
  }, {
    id: "in",
    label: "India",
    flag: "🇮🇳",
    base: "https://in.api.hellotars.com"
  }, {
    id: "qa",
    label: "Qatar",
    flag: "🇶🇦",
    base: "https://qa.api.hellotars.com"
  }]
};

export const r_0 = undefined

This reference covers API keys for the Tars HTTP APIs, including the campaign-bound keys that only their own campaign endpoint accepts.

## Where keys live

API keys are managed under **Settings** → **Integrations**, in the **API Keys** panel. API access requires a paid plan. On the Free plan the panel shows an **Upgrade plan** link instead.

## Create a key

Click **Create key** and fill in the dialog.

| Field           | Description                                        |
| --------------- | -------------------------------------------------- |
| **Label**       | A name for the key, for example "Production CRM"   |
| **Scope**       | **Whole organization** or **Specific AI agent**    |
| **Agent**       | The target agent, shown only for agent-scoped keys |
| **Permissions** | One or more permission scopes (see below)          |

The full key is shown once, immediately after creation. Copy it before you close the dialog. After that, the dashboard shows only the key prefix.

## Key scope

| Scope                  | Behavior                                                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Whole organization** | Acts across every agent and can manage organization-level data such as end users                                                                      |
| **Specific AI agent**  | Bound to one agent. Requests against any other agent return `403`. Cannot hold the **End-users** permission, because end users are organization-level |

## Permission scopes

Each key holds one or more permission scopes. A request outside the key's scopes returns `403`.

| Permission    | Grants                                                          | Endpoints                                                     |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
| **Triggers**  | Start agent conversations from your backend                     | [Start conversations](/docs/developer/api/start-conversations)     |
| **Channels**  | Send messages on a connected channel                            | [Send channel messages](/docs/developer/api/send-channel-messages) |
| **End-users** | Read, create, update, and delete end-user records               | [End users API](/docs/developer/api/end-users)                     |
| **Campaigns** | Carried by campaign-bound keys, which the campaign page creates | Campaign endpoints                                            |

Campaign keys are created on the campaign page, not in this dialog. They appear in this same key list, scoped to their campaign. A campaign endpoint accepts only the key bound to that campaign, so an organization or agent key holding **Campaigns** cannot call one. See [Webhook campaigns API](/docs/developer/api/webhook-campaigns).

## What the key list shows

Each key row displays its label, key prefix, scope, permission badges, **Created** date, and **Last used** date. **Last used** shows "Never" until the first authenticated call.

## Revoke a key

Click **Revoke** on a key row and confirm. Revocation takes effect immediately. Any integration using the key fails on its next request. Revocation cannot be undone.

## Authenticate requests

Every API request sends the key as a Bearer token.

```bash theme={null}
curl -X POST \
  https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

| Status | Cause                                                                       |
| ------ | --------------------------------------------------------------------------- |
| `401`  | Missing `Authorization` header, or an invalid or revoked key                |
| `403`  | Key not authorized for this agent, or the key lacks the required permission |
| `404`  | No agent matches the requested ID                                           |

## Base URL

Every request goes to the base URL for your organization's region. Your data stays in that region, so a key issued in one region does not work in another. Pick the row that matches your organization.

<table>
  <thead>
    <tr><th>Region</th><th>Base URL</th></tr>
  </thead>

  <tbody>
    {api.regions.map((r_0) => (
            <tr key={r_0.id}>
              <td>{r_0.flag} {r_0.label}</td>
              <td><code>{r_0.base}</code></td>
            </tr>
          ))}
  </tbody>
</table>

Code samples on these pages use the {api.regions[0].label} base URL. The dashboard shows the right base URL for your organization beside your API keys.

Every API page carries an interactive playground. Pick your region from the server list at the top of the playground, paste a key, and send a real request from the page.

## The OpenAPI spec

Each region serves its own machine-readable spec at `/api/openapi.json`, and the endpoint needs no key. Import that URL into Postman, Insomnia, or a client generator to pick up every endpoint, schema, and error shape. The playground on each API page runs against the same definition.

```bash theme={null}
curl https://us.api.hellotars.com/api/openapi.json
```

`GET /api/health` also needs no key. It returns `{ "status": "ok" }` with a timestamp, which makes it a quick reachability check from your network.

## Rate limits

The trigger and channel send endpoints return `429` with a `Retry-After: 60` header when a request is over the limit. Wait 60 seconds, then retry. Webhook campaign endpoints apply their own per-organization and per-key limits.

## Related pages

* [Start conversations API](/docs/developer/api/start-conversations)
* [Send channel messages API](/docs/developer/api/send-channel-messages)
* [End users API](/docs/developer/api/end-users)
* [Webhook campaigns API](/docs/developer/api/webhook-campaigns)