Platform

Retrieve an API key

One of this newsletter's API keys, by id, revoked or not. Needs settings: write. Carries no secret: Commune stores none to return.

A key belonging to another newsletter answers 404, whichever newsletter the caller names.

get/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)

Query parameters

expandstring

Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

fieldsstring

Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

Response

The key.

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.