Commune

403forbidden

Newsletter not reachable

The credential is valid but cannot act on the newsletter you addressed, or on the key you tried to revoke.

The credential was recognised, and it is not allowed to do this particular thing. Almost always that is because the request names a newsletter the credential does not reach. A credential reaches the newsletters it was granted when it was created, and only for as long as the person it belongs to can still act on them.

Commune answers 403 both when the newsletter exists and your credential does not reach it and when the identifier names no newsletter at all, so that the API cannot be used to test which handles exist. That means a misspelt handle is a `403`, not a `404`.

A credential that reaches the newsletter but holds too little on it gets insufficient_scope instead, which tells you which permission to add.

Why it happens, and how to fix it

  1. The credential does not reach the newsletter named

    The {newsletter} in the path, or the newsletter query parameter, names a newsletter this credential was never granted, or the id or handle is misspelt. param is newsletter and the message quotes what you sent.

    Fix: Call GET /newsletters with the same credential: it lists exactly the newsletters it reaches, with their id and handle. Use one of those. If the newsletter you want is missing, its owner or someone on its team has to mint a key that includes it on Settings, API keys, or your app has to be authorised for it again.

  2. The owner of the credential lost access to the newsletter

    A credential acts on a newsletter only while the person it belongs to can. If they were removed from the newsletter's team, or the newsletter's owner or an admin cut this credential off on the newsletter's API access page, it stops reaching it at once. When it reaches nothing at all, the message quotes an empty value ("").

    Fix: Check GET /newsletters: if it comes back empty, the credential reaches nothing and needs replacing. Ask a current owner or admin of the newsletter to mint a key for the integration, or to restore the person's place on the team.

  3. Revoking a key that belongs to somebody else

    DELETE /api-keys/{key} turns a key off everywhere it works, so a credential may only revoke keys belonging to the same person (itself included). You can see another person's key through GET /newsletters/{newsletter}/api-keys when it reaches a newsletter yours does, and still not revoke it.

    Fix: Ask the key's owner to revoke it on their Settings, API keys page. To stop it reaching one newsletter without touching it anywhere else, an owner or admin of that newsletter revokes its access on the newsletter's API access page.

Retrying

No: the same request is refused until the credential is granted the newsletter, so address a newsletter from GET /newsletters or use a credential that reaches this one.

Example response

HTTP 403
{
  "error": {
    "code": "forbidden",
    "message": "This credential does not reach the newsletter \"the-weekly-brief\". A credential reaches the newsletters it was granted, and only for as long as the person it belongs to can act on them. Call `GET /newsletters` to see which ones this credential reaches right now.",
    "param": "newsletter",
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/forbidden"
  }
}

Often confused with insufficient_scope, not_found, unauthorized.