Authentication & API keys
Every request needs an API key in the Authorization header, over HTTPS:
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.