Creating a key
Sign in to the developer portal and create a key. Give it a label that will
still mean something to you in six months — "staging ingest", not "test2".
The secret is shown once. It is stored only as a hash, so nobody — including
us — can recover it afterwards. If you lose it, rotate.
A key is presented as a header, never in a query string:
GET /api/v1/events HTTP/1.1
Host: developers.placetomingle.com
X-PTM-Api-Key: ptms_<keyid>.<secret>
A query string ends up in server logs, browser history and referrer headers. A
header does not.
Rotating
Rotation is create-then-revoke, in that order, with both keys live in between:
- Create a second key with the same scopes.
- Deploy it.
- Confirm traffic has moved — the portal shows last-used per key.
- Revoke the old one.
Doing it the other way round is an outage.
Revoking
Revocation is immediate and irreversible. A revoked key cannot be un-revoked;
create a new one.
Expiry and idle revocation
Every key has a mandatory expiry, and a key that goes unused for a long period
is revoked automatically. Both are deliberate: a credential that never expires
is a credential that outlives the person who created it. Watch the expiry date
and rotate ahead of it rather than after the first 401.
If a key leaks
Revoke it first, then work out how it leaked. In that order, always.