Creator websites

Revoke a publishable key

Turns a key off. Needs settings: write, and is a write.

Every request made with it is refused from then on, so any page still carrying it stops being able to read this newsletter's data. Deploy the replacement before calling this.

The row survives and keeps its name, its prefix and the date it was turned off, because the question asked after an incident is "which key was that", and a row that vanished on revocation cannot answer it. Revoking an already revoked key succeeds and keeps the original date.

There is no un-revoke, for the reason there is none for an API key: a revocation that could be undone would let whoever found the key put it back.

Publishes no event.

delete/publishable-keys/{publishable_key}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/publishable-keys/{publishable_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, turned off.

object'publishable_key' required

Always publishable_key.

idstring uuid required

Stable identifier.

namestring required

Your label for the key. Not unique: two keys called Website is your business rather than Commune's.

key_prefixstring required

The non-secret start of the key, for recognising it. Never used to look one up.

secretstring nullable required

The key itself, present exactly once: in the response to the call that minted it. Null in every other response, including a list, because Commune keeps only a digest of it and cannot return it again. A key you have lost is a key you rotate.

allowed_originsstring[] required

Extra browser origins this key is accepted from, on top of the newsletter's own. For a development machine or a staging host. Each entry is a bare origin: a scheme, a host and an optional port, with no path, no trailing slash and no wildcard, because an origin check that accepted a wildcard would be one anybody could pass.

originsstring[] required

Every origin this key is accepted from, which is what allowed_origins adds to rather than replaces: the newsletter's live website hostname when it has one, the Commune-provided subdomain, and then the extra origins above. An empty allowed_origins therefore means "the real website and nowhere else" rather than "nowhere".

rate_limit_per_minuteinteger required

How many requests a minute this key may make, counted across every page using it. It is a property of the key rather than of the newsletter, so a staging key can be given a small one.

monthly_request_quotainteger nullable required

A monthly ceiling on requests, or null for none.

created_atstring date-time required

When the key was minted.

last_used_atstring date-time nullable required

When a request last arrived with it, to the nearest minute. How you tell which key your deployed pages are actually calling before you turn the other one off. Null for a key nothing has used.

revoked_atstring date-time nullable required

When the key was turned off, or null while it works. Revocation is a stamp rather than a deletion: a key that was abused has to stay nameable.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "key_prefix": "cmn_pk_7Qa2Lk9x",
  "allowed_origins": [
    "http://localhost:5173"
  ]
}

Changes

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