Creator websites

Create a publishable key

Mints a read-only key your website's page source can read this newsletter's public data with. Needs settings: write, and is a write.

The secret is in this response and nowhere else. Commune keeps only a digest of it, so no later call returns it; a key you have lost is a key you rotate.

It is cmn_pk_-prefixed rather than cmn_sk_ because it is meant to be public: it goes in HTML that anybody can read. What stops that being a problem is what the key can do, which is read what this newsletter has already published, from this newsletter's own website origins, inside a rate limit. Never an email address, never a draft, never a tag-scoped article, and never another newsletter.

allowed_origins are extra origins, for a development machine or a staging host. The newsletter's own website origins are always accepted and do not need listing, which is why the empty default means "the real website and nowhere else" rather than "nowhere".

This is the one place in this API where a credential mints a credential. An API key cannot mint an API key, because a key that could would outlive its own revocation. Neither half of that holds here: this key can mint nothing, and it reaches one newsletter's published rows by its own row rather than by a grant anybody could widen.

Publishes no event.

post/newsletters/{newsletter}/publishable-keys

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/newsletters/{newsletter}/publishable-keys
  • 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.

Request body

namestring required

Your label for the key.

allowed_originsstring[]

Extra origins to accept the key from, on top of the newsletter's own website origins, which are always accepted. Omit for none.

rate_limit_per_minuteinteger

Requests a minute this key may make.

monthly_request_quotainteger nullable

A monthly ceiling on requests. Omit for none.

Response

The key, with its secret. Store it now: this is the only response that carries it.

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.