Creator websites

Rotate a publishable key

Mints a replacement carrying the same name, origins, rate limit and quota as the key you named. Needs settings: write, and is a write.

The old key keeps working. That is the whole point of rotating rather than revoking: a publishable key lives in deployed HTML, so the order has to be mint, deploy, then revoke. Two live keys in between is the normal case rather than a violation, and last_used_at on each is how you tell when the old one has stopped being called.

Revoke a publishable key is the third step, and nothing here does it for you: Commune cannot know when your pages have gone out.

Rotating a revoked key is allowed and is the ordinary way to replace one you have lost: it copies the settings and mints a new secret, and the revoked key stays revoked.

As with minting, the secret is in this response and nowhere else.

Publishes no event.

post/publishable-keys/{publishable_key}/rotate

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/publishable-keys/{publishable_key}/rotate
  • 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 new key, with its secret. The key you named is untouched and still live.

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.