# Authentication & API keys

Every request needs an API key in the `Authorization` header, over HTTPS:

```http
GET /api/v1/monitors HTTP/1.1
Host: dev.tickingora.com
Authorization: Bearer 12|tk_9b2f…
```

The dashboard session cookie is **not** accepted by the API — use a key, even from your own scripts.

## Creating keys

Open **Settings → API keys** in the dashboard. Each key has:

| Property | Notes |
| --- | --- |
| Name | For you, e.g. `CI`, `backup server`, `coding agent`. |
| Scopes | What the key may do (below). Choose the minimum needed. |
| Expiry | Never, 30, 90 or 365 days. Expired keys get `401 UNAUTHENTICATED`. |

The secret is shown **once**, when the key is created. Tickingora stores only a hash, so a lost key cannot be recovered — create a new one and revoke the old one. Keys start with `tk_` after the numeric id (`12|tk_…`), which makes leaked keys easy to detect by secret scanners. Up to 10 keys per account.

## Scopes

| Scope | Allows |
| --- | --- |
| `monitors:read` | List and read monitors, run history. |
| `monitors:write` | Create, update, pause, resume, delete monitors, rotate Heartbeat tokens. Also allows reading monitors. |
| `incidents:read` | Read incident history (`GET /monitors/{id}/incidents`). |

`GET /account` (plan, usage and the key's own scopes) works with **any** scope.

A request without the required scope gets `403 FORBIDDEN_SCOPE` with `details.required_scopes`.

A read-only key (`monitors:read`) is a good fit for dashboards and status scripts: it can never create, change or delete monitors, and it never reveals Heartbeat ping URLs.

## API keys vs. Heartbeat ping URLs

They are different secrets with different power:

| | API key | Heartbeat ping URL |
| --- | --- | --- |
| Purpose | Manage your account's monitors | Report that **one** job ran |
| Where it lives | Your automation, CI, agent | The job itself (cron, script) |
| Stored as | Hash — shown once, when created | Hash — shown once, on create and rotation (plus an idempotent replay of the same create within 24 h) |
| Where you see it | Settings → API keys, right after creating it | `POST /monitors`, `rotate-token`, or the dashboard right after creating/rotating |
| Lost it? | Create a new key, revoke the old one | Rotate: `POST /monitors/{id}/rotate-token` |
| If leaked | Revoke the key in Settings | Rotate it |

Never put an API key into a URL or a ping command.

## Revoking

**Settings → API keys → Revoke** stops the key immediately. Revoking does not affect monitors or their ping URLs.

## Usage log

Tickingora records each API request (key, method, path, status, IP address, duration — never the key or body) for 30 days, and shows *last used* next to every key.