---
url: /api/authentication.md
description: >-
  API key format, header shape, key lifecycle, disable versus revoke semantics,
  and the active-key cap.
---

# Authentication

Every request to the API — both REST and the SSE stream — requires an API key sent as a Bearer token.

```bash
curl https://app.telegramtometatrader.com/api/v1/trades \
  -H "Authorization: Bearer ttmt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

The header name is case-insensitive (`authorization` works too). Never put the key in a query parameter — only the `Authorization` header.

***

## Key format

Keys have the prefix `ttmt_live_` followed by 43 Base64URL characters (256 bits of entropy from a CSPRNG). The prefix is deliberately structured to be caught by GitHub secret scanning and similar tools.

```
ttmt_live_<43-char Base64URL body>
```

Example (this is not a real key):

```
ttmt_live_A3kZvR8mXqNpLdFhYcWsJoTeUiByGxKjIl7QfPeVsM9
```

Only the SHA-256 hash of the key is stored. The raw secret is shown exactly once at creation — you cannot retrieve it after that point.

***

## Managing keys

Keys are managed on the **Connectors** page, in the **Developer API** tab.

* **Create** — gives you the raw key once.
* **Revoke** — permanently invalidates the key. Revoked keys return `401`.
* **Active-key cap** — you can have a limited number of active keys at a time (currently 5). If you hit the cap, revoke an unused key before creating a new one.

Name your keys by what they do (e.g., `trading-bot`, `analytics-script`) so you can revoke individual integrations without cycling everything.

***

## Disable vs. revoke

There are two distinct ways a key stops working:

| State | What happened | Key persists | Effect |
|:---|:---|:---|:---|
| **Revoked** | You deleted the key in the dashboard | No | Returns `401` until you create a new one |
| **Access disabled** | Admin disabled API access for your account (e.g., subscription enforcement) | Yes | Returns `403` while disabled |

When access is re-enabled, your existing keys start working again — you do not need to create new ones. This is intentional: suspension is an account-level gate, not a credential wipe.

***

## Auth failure responses

All failures return `application/problem+json`:

| Status | Cause |
|:---|:---|
| `401` | Missing header, malformed token, unknown key, or revoked key |
| `403` | Valid key but API access is disabled for the account |
| `405` | Non-GET method — the surface is read-only |

Unknown and revoked keys both return `401` — the API does not distinguish them (no enumeration oracle).

***

## Security rules

* Never put the key in a URL query parameter. It will end up in server logs.
* Never commit a key to source control. Use an environment variable.
* Use one key per integration so you can revoke it individually.
* The key gives read access to your data only. It cannot write, trade, or access any other user's data.
