Platform

Revoke an API key

Stops this credential working. The next request made with it is refused the same way a string that was never issued is refused.

The row survives. DELETE stamps the key as revoked rather than removing it, so it stays in the list with its revoked_at. Nothing in this API removes a key.

Revocation only goes one way. No operation here revives a revoked key, and none mints a new one, so through this API the set of working credentials on a newsletter can only get smaller. Mint a replacement in Commune's settings.

A key may revoke itself, which is what an integration that knows it has leaked, or a job finished with its credential, should do. self on the list operation says which key that is.

A key may also revoke its siblings: the other credentials belonging to the same person.

A credential belonging to somebody else answers 403, even when it reaches the same newsletter and GET /api-keys/{key} returns it. Cutting a credential off one newsletter rather than off everything is done in Commune's settings instead.

Revoking a key that is already revoked succeeds and returns it unchanged, with its original revoked_at, so a retry after a dropped response is not a failure.

Never refused for payment, so no 402. Publishes no event: the credential that was revoked learns it on its next request.

delete/api-keys/{key}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/api-keys/{key}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: settings:write)

Headers

Idempotency-Keystring required

A value of your choosing naming the change this request is making.

Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an Idempotent-Replay: true response header. Send a different value for a different change: a key reused for a request that differs in any way answers 409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.

A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.

Required, not optional.

Response

The key, as it now stands. revoked is true, live is false, and revoked_at is when it was first turned off.

object'api_key' required

Always api_key.

idstring uuid required

Stable identifier. This is what addresses the key in a path; the secret never appears in a URL and never will.

namestring required

What the creator called it when they minted it. Not unique: two keys called staging are a creator's problem and not an error.

key_prefixstring required

The leading fifteen characters of the secret, which is all of it that Commune keeps. Enough to recognise which key an integration is configured with, and short enough that it is not itself usable.

pinned_versionstring date required

The contract version a request made with this key resolves to when it sends no Commune-Version header. Stamped when the key was minted, so a newer contract shipping does not move an existing integration.

liveboolean required

Whether a request made with this key right now would be authenticated. False once it has been revoked, and false once it has expired. Computed against Commune's own clock with the same test the authentication path applies, so it is a more reliable answer than comparing expires_at to a client's clock.

revokedboolean required

Whether somebody turned this key off. A revoked key never becomes live again: nothing in this API can revive one.

revoked_atstring date-time nullable

When it was turned off, or null while it is not. A second revocation does not move it.

expires_atstring date-time nullable

When the key stops working on its own, or null for one that never does. Expiry and revocation are separate: an expired key has not been revoked and reports revoked false.

last_used_atstring date-time nullable

The last time a request was authenticated with this key, or null if none ever has been. Written at most once a minute, so it is accurate to the minute rather than to the request, which is the resolution the question behind it needs: is anything still calling with this, and can it be revoked.

selfboolean required

True for the one key the current request was made with, and false for every other. A caller holds a secret rather than an id, so this is the only way it can tell which of these rows is itself, which is what it needs before revoking any of them. False on every row for a request made with an OAuth access token, since no key is that credential.

created_atstring date-time required

When the key was minted.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "key_prefix": "cmn_sk_7Qd2xLpA",
  "pinned_version": "2026-08-26",
  "created_by": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.