API keys

API keys authenticate scripts, CI pipelines and anything else that talks to the public API on your behalf. They’re separate from ping tokens, and the distinction is worth getting right:

• A ping token checks one monitor in. It’s per monitor, it lives on the box that runs the job, and it can’t read or change anything.
• An API key manages your workspace. It’s per workspace and it can create, read and modify monitors.

A key is presented as a bearer token:

curl -H "Authorization: Bearer deadpost_live_…" https://api.deadpost.dev/v1/monitors

You see it once

The full key is shown exactly once, at creation. After that only a prefix and the last four characters are stored for display — deadpost_live_…a4f9 — which is enough to tell two keys apart in a list and not enough to use.

If you lose it, create a new one and delete the old. There is no way to reveal it again, deliberately: a key you can re-read from a dashboard is a key that leaks the moment anyone gets into the dashboard.

Scopes

Keys are scoped per resource, read and write separately.

Scope	Grants
read:monitors	View monitor configuration and status.
write:monitors	Create, update and delete monitors.

Give a key the narrowest set that does its job. A dashboard that displays monitor status wants read:monitors and nothing else — and then it cannot delete a monitor no matter what goes wrong with it.

The ping token is write-scoped

A monitor’s ping token is only returned to keys holding write:monitors. A read-only key sees the monitor without it.

That surprises people, because reading a field feels like a read. But holding a ping token lets you check a monitor in — which means masking a real outage — so it’s a capability, not data. Every workflow that legitimately needs one (provisioning, generating crontab lines, Terraform) is configuring monitoring rather than observing it.

If a field you expect is missing from a response, this is usually why: absent means “this key isn’t permitted to see it”, not “the value is unset”.

Expiry and rotation

A key can be given an expiry, and expired keys stop working at that moment.

Set one on anything handed to a third party or created for a time-boxed piece of work. It converts “we should clean that up” into something that happens whether or not anyone remembers.

To rotate: create the new key, deploy it, confirm traffic has moved, then delete the old one. Deleting first means a gap where nothing works.

Usage

Each key records when it was last used, so a key with no recent activity is either a rotation you finished or something you can delete. Both are worth acting on — an unused key is pure risk with no upside.

Keeping keys safe

• Environment variables or a secrets manager, never a repository.
• One key per consumer, so revoking one doesn’t take down the others — and so “which of these is the CI key?” has an answer.
• Delete keys for people and systems that have gone away.

Endpoint reference

This page covers authentication. Endpoint-by-endpoint reference for the public API isn’t published yet — the /v1 surface is still being finalised ahead of launch, and documenting shapes that may still change would be worse than not documenting them.