API keys

An API key is the credential that authenticates every request to this API. It is pinned to one team, carries a set of abilities, and can be restricted to specific ontologies. Keys are a resource of the API itself, so an integration can mint the credential its own workers use, narrow one that turned out to be over-granted, revoke a colleague's when they leave, and — most importantly — rotate itself on a schedule with no human in the console.

The API key model

The security model

A session in the Synex application belongs to a human who already holds every ability their team has, so the console's key page has nothing to constrain. This surface has no such luxury: the thing creating a key is itself a key. A create endpoint that did not constrain its result would be a privilege-escalation primitive — one leaked read-only key would be one POST away from an unlimited one, and the whole ability system would be advisory rather than enforced.

One rule governs everything here: a key may never produce a key broader than itself, along any axis. Four constraints implement it.

Abilities are subset-constrained

Every entry in abilities must be one the calling key already holds. Anything else is 400 ability_not_grantable with param set to abilities. The same check runs on PATCH, so a key cannot raise another key above its own set either.

Rolling is subset-constrained too

This is easy to mistake for excess caution, and it is not. Rolling returns the replacement's secret, so being able to roll a key is exactly equivalent to being handed that key's abilities. Without the check the subset rule on create would be decorative: a key holding api_keys:write and nothing else could not mint passports:write, but could roll a team key that has it and read the new secret straight out of the response.

So the same question create asks — could the caller have granted this? — is asked of the target's existing abilities and scopes. If the answer is no the request is refused with 403 key_not_rollable on api_key, and nothing is written: the target keeps its secret and its rolled_at stays null.

The status code differs from the create rule on purpose. Minting an ability you do not hold is a bad request (400); rolling a key you are not entitled to is a permission failure (403). Rolling yourself is always allowed and skips the check entirely.

Scopes narrow, never widen

If the calling key is ontology-scoped on an ability, a key it creates must name a subset of the caller's ontologies for that ability. Refusals are 400 scope_not_grantable on scopes.

The case worth internalising: omitting the scope is rejected too. An unscoped ability reaches every ontology in the team, so silence is the widest possible request rather than the narrowest. A caller restricted to one ontology cannot mint an unrestricted passports:write key by leaving scopes out, and cannot unscope an existing one by sending "scopes": null on a PATCH.

A child may not outlive its parent

A perpetual child of a two-week key is a two-week key with an indefinite escape hatch — revoking the parent would leave the child running. Every rejection here is 400 parameter_invalid on expires_at, whatever the reason: malformed, in the past, beyond the caller's deadline, or omitted where required.

Expiry is set once. PATCH does not accept it — a deadline that can be pushed back is not a deadline. Sending expires_at on a PATCH is ignored, not rejected, so do not read the 200 as confirmation that it moved.

The team is inherited, never requested

There is no team field on any request here. A created key is pinned to the calling key's team, so a key cannot mint into a tenant it cannot already reach. Sending team or team_id in the body changes nothing — the value is ignored.

Team-scoped here, per-user in the console

Both are correct for what they are. The console page is a personal credential-management screen; the API is a team-administration surface. Scoping the API per-user would mean a departed colleague's key could never be revoked by an integration, which is exactly when you most want to.

Two consequences: GET /v1/api_keys will normally return more rows than the console shows you, so do not treat the console as the authoritative inventory; and a key with api_keys:write can revoke any of the team's keys, including yours and including itself. That is the main reason the ability is flagged sensitive and sits outside the default set.

A key belonging to another team is 404 resource_missing on every addressable route, never 403 — a team must not be able to probe whether an id exists in another tenant. A non-numeric id reads the same way.

List API keys

curl https://api.synexcloud.com/v1/api_keys \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "4418",
      "object": "api_key",
      "name": "Kestrel ingest worker",
      "abilities": [
        "passports:read",
        "passports:write",
        "imports:read",
        "imports:write"
      ],
      "scopes": {
        "passports:write": {
          "ontologies": ["ontology_7d1f4a2b9c3e5081"]
        }
      },
      "metadata": { "service": "kestrel-ingest" },
      "last_used_at": "2026-07-28T09:12:44Z",
      "expires_at": "2027-01-14T00:00:00Z",
      "rolled_at": null,
      "rolled_to": null,
      "rolled_from": "4401",
      "created_at": "2026-07-14T11:03:19Z"
    },
    {
      "id": "4402",
      "object": "api_key",
      "name": "Kestrel reporting reader",
      "abilities": ["passports:read", "ontologies:read"],
      "scopes": null,
      "metadata": {},
      "last_used_at": null,
      "expires_at": null,
      "rolled_at": null,
      "rolled_to": null,
      "rolled_from": null,
      "created_at": "2026-06-02T08:41:55Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/api_keys"
}

Create an API key

curl https://api.synexcloud.com/v1/api_keys \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kestrel ingest worker",
    "abilities": ["passports:read", "passports:write", "imports:read", "imports:write"],
    "scopes": { "passports:write": { "ontologies": ["ontology_7d1f4a2b9c3e5081"] } },
    "expires_at": "2027-01-14T00:00:00Z",
    "metadata": { "service": "kestrel-ingest" }
  }'

{
  "id": "4418",
  "object": "api_key",
  "name": "Kestrel ingest worker",
  "secret": "synex_sk_9f4b2e7a0c6d1358a2e5b8c3d0f7469125ae8b3c",
  "abilities": [
    "passports:read",
    "passports:write",
    "imports:read",
    "imports:write"
  ],
  "scopes": {
    "passports:write": {
      "ontologies": ["ontology_7d1f4a2b9c3e5081"]
    }
  },
  "metadata": { "service": "kestrel-ingest" },
  "last_used_at": null,
  "expires_at": "2027-01-14T00:00:00Z",
  "rolled_at": null,
  "rolled_to": null,
  "rolled_from": null,
  "created_at": "2026-07-28T09:12:44Z"
}

Retrieve an API key

curl https://api.synexcloud.com/v1/api_keys/4418 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "4418",
  "object": "api_key",
  "name": "Kestrel ingest worker",
  "abilities": [
    "passports:read",
    "passports:write",
    "imports:read",
    "imports:write"
  ],
  "scopes": {
    "passports:write": {
      "ontologies": ["ontology_7d1f4a2b9c3e5081"]
    }
  },
  "metadata": { "service": "kestrel-ingest" },
  "last_used_at": "2026-07-28T09:12:44Z",
  "expires_at": "2027-01-14T00:00:00Z",
  "rolled_at": null,
  "rolled_to": null,
  "rolled_from": "4401",
  "created_at": "2026-07-14T11:03:19Z"
}

Update an API key

curl -X PATCH https://api.synexcloud.com/v1/api_keys/4418 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kestrel ingest worker (EU)",
    "abilities": ["passports:read", "passports:write"],
    "scopes": { "passports:write": { "ontologies": ["ontology_7d1f4a2b9c3e5081"] } },
    "metadata": { "region": "eu-west" }
  }'

{
  "id": "4418",
  "object": "api_key",
  "name": "Kestrel ingest worker (EU)",
  "abilities": ["passports:read", "passports:write"],
  "scopes": {
    "passports:write": {
      "ontologies": ["ontology_7d1f4a2b9c3e5081"]
    }
  },
  "metadata": {
    "service": "kestrel-ingest",
    "region": "eu-west"
  },
  "last_used_at": "2026-07-28T09:12:44Z",
  "expires_at": "2027-01-14T00:00:00Z",
  "rolled_at": null,
  "rolled_to": null,
  "rolled_from": "4401",
  "created_at": "2026-07-14T11:03:19Z"
}

Revoke an API key

curl -X DELETE https://api.synexcloud.com/v1/api_keys/4418 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "api_key",
  "id": "4418",
  "deleted": true
}

Roll the calling key

curl -X POST https://api.synexcloud.com/v1/api_keys/self/roll \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "4432",
  "object": "api_key",
  "name": "Kestrel ingest worker",
  "secret": "synex_sk_6b1e948d0f2a37c5be804d1a7f3c92e60b58da47",
  "abilities": [
    "passports:read",
    "passports:write",
    "imports:read",
    "imports:write"
  ],
  "scopes": {
    "passports:write": {
      "ontologies": ["ontology_7d1f4a2b9c3e5081"]
    }
  },
  "metadata": { "service": "kestrel-ingest" },
  "last_used_at": null,
  "expires_at": "2027-01-14T00:00:00Z",
  "rolled_at": null,
  "rolled_to": null,
  "rolled_from": "4418",
  "created_at": "2026-07-28T10:04:02Z"
}

Roll an API key by id

curl -X POST https://api.synexcloud.com/v1/api_keys/4418/roll \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "4431",
  "object": "api_key",
  "name": "Kestrel ingest worker",
  "secret": "synex_sk_3d0a7c9e2b6f451870ad4c1e9b2f6538c7a04e1b",
  "abilities": [
    "passports:read",
    "passports:write",
    "imports:read",
    "imports:write"
  ],
  "scopes": {
    "passports:write": {
      "ontologies": ["ontology_7d1f4a2b9c3e5081"]
    }
  },
  "metadata": { "service": "kestrel-ingest" },
  "last_used_at": null,
  "expires_at": null,
  "rolled_at": null,
  "rolled_to": null,
  "rolled_from": "4418",
  "created_at": "2026-07-28T10:04:02Z"
}

The rotation workflow

Rolling issues a new secret while the old one keeps working, so a deploy never lands in a window where neither authenticates:

1. Roll. POST /v1/api_keys/self/roll returns the replacement, secret included. This is the only time that value is ever shown.
2. Deploy the new secret. Write it wherever your workers read credentials from and restart them. Both secrets authenticate during this step, so ordering does not matter and a partial rollout is safe.
3. Do nothing. The old secret expires on its own 24 hours after the roll. There is nothing to clean up and no second call to make.

Three details before you automate it:

• The window never extends a key. The overlap ends at min(now + 24h, the key's existing expiry). A key already due to expire inside the next day keeps its own earlier deadline.
• A second roll does not restart the window. It mints another replacement and re-applies the same rule against the deadline the first roll wrote, so the original window stands. Rotate at the pace of your deploys, not faster.
• The replacement inherits the calling key's expiry, not the rolled key's.

Lineage

The retiring key stays readable at its own id until its window elapses, so both halves are inspectable while the rotation is in flight. That is why the roll response is just the replacement, with no previous_key envelope — the other half is a GET away.

Rolling the same key twice leaves two live replacements but one forward pointer: rolled_to names the most recent. The earlier replacement is not lost — it is still findable by its own rolled_from, which names the same parent. If you walk lineage, walk it backwards from a key rather than forwards from a parent.

The secret is unrecoverable

Only a hash is stored. secret is returned in exactly three responses — create, roll and self-roll — and is omitted from everything else: reads, list rows, PATCH responses, and event payloads.

There is no recovery endpoint and no support path that can retrieve one. A key whose secret is lost must be rolled — which is cheap — or revoked and replaced. Capture the value when it is issued.

Events

Three types land on the change feed, and none of them ever carries a secret — the snapshot is produced by the same code that serves the GET, which structurally cannot render one.

There is deliberately no api_key.updated. A PATCH here changes labelling or narrows authority, and neither is a state change another system needs pushed to it.

Because api_key.revoked describes a row that no longer exists, it is one of the few events whose data.object cannot be re-fetched. Treat the snapshot as the record.

Errors

See errors for the shared envelope.