intelligent.pageDocs

Tokens and keys

Project tokens versus Server keys: what each may do, how to create and revoke them, origin pinning, rotation without downtime, and what to do if one leaks.

A Project has two kinds of credential and they are not interchangeable. Choosing the wrong one is either a broken integration or an exposed one, so the difference is worth thirty seconds.

At a glance

Both are generated randomly, stored only as a SHA-256 hash, and shown once, in the response to the call that created them. There is no route that returns a key again. Lists show the first 16 characters, which is enough to recognise one and not enough to use it.

Why a Project token is safe to publish

It is write-only by construction, not by policy. Every route that returns data goes through one read check, and that check rejects a ipa_pub_ credential before it looks at anything else. There is no setting, role or header that changes this.

So the worst an extracted Project token allows is sending events into your own Project: noise, bounded by your rate limit and your quota, and identifiable in a report by the Source and properties it arrives with. It is not a data-exposure incident. A leaked Server key is: it reads every report in the Project and can change its settings.

Creating a key

From Project settings, or over the API with a Server key or an owner's read token:

curl -X POST https://t.intelligent.page/v1/projects/acme-shop/keys \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer ipa_sec_REPLACE_ME' \
  -d '{ "kind": "secret", "label": "orders worker" }'

{
  "key": "ipa_sec_…",
  "record": {
    "id": "k_8fa1",
    "projectId": "acme-shop",
    "kind": "secret",
    "prefix": "ipa_sec_Ab12Cd34",
    "label": "orders worker",
    "createdAt": "2026-09-28T09:15:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null
  }
}

kind is public or secret. 201 on success. Copy key now: it is not retrievable later.

Give every key a label naming the thing that will use it. "orders worker", "marketing site", "warehouse backfill". Six months later, the label is the only way to know whether revoking one breaks anything.

Listing and revoking

curl -s https://t.intelligent.page/v1/projects/acme-shop \
  -H 'Authorization: Bearer ipa_sec_REPLACE_ME'

returns the Project with its keys, members and this month's usage. Each key carries prefix, label, createdAt, lastUsedAt and revokedAt.

curl -X POST https://t.intelligent.page/v1/projects/acme-shop/keys/k_8fa1/revoke \
  -H 'Authorization: Bearer ipa_sec_REPLACE_ME'

{ "ok": true }

Revocation is permanent: a revoked key is never valid again, and 404 comes back if the key id is not this Project's. Writes with a revoked key answer 401.

lastUsedAt is written at most once every five minutes per key, so it is the right field for "is anything still using this" and the wrong field for a timeline.

Rotating without downtime

  1. Create the new key and label it.
  2. Deploy the new key everywhere the old one is used.
  3. Watch lastUsedAt on the old key stop moving. Give it longer than your longest cache or deployment lag, and remember the five-minute write interval.
  4. Revoke the old key.

Do not revoke first. There is no grace period and no warning: the next write is a 401.

Rotate a Server key on the usual schedule and immediately if it has ever been in a log, a support ticket, a screenshot or a repository. Rotating a Project token is rarely worth the deployment, since it is publishable by design; rotate it if you are actually being flooded, and pin origins at the same time.

Origin pinning

A Project can list the origins its Project token may be used from:

curl -X POST https://t.intelligent.page/v1/projects/acme-shop/settings \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer ipa_sec_REPLACE_ME' \
  -d '{ "settings": { "allowedOrigins": ["https://shop.example.com", "https://www.example.com"] } }'

While the list is empty, any Origin may write with the token: the token is the credential, which is the usual arrangement for a public website. Once it is non-empty, a browser request carrying an Origin header outside the list is refused. At most 50 origins, each http:// or https:// with a host and no path.

Two things pinning does not do. It does not stop a non-browser client, which simply sends no Origin header, so it is not a security boundary. And it will break your own site the moment you add a domain and forget the list, which is worth a note next to whoever manages DNS.

Where a credential may travel

If a key leaks

Server key. Revoke it first and ask questions afterwards. Then rotate every other credential it could have read or changed, and check the Project's members and settings for anything it altered.

Project token. Nothing is exposed. If it is being abused, pin your origins, create a new token, deploy it and revoke the old one.

The management routes

Full request and response schemas: API reference.

Next