Authentication

The API accepts 2 different authentication methods:

Oauth2

An OAuth access token, sent as Authorization: Bearer <token>. The walkthrough of the whole flow is at usecommune.dev/use-cases/build-an-integration: discovery, registration, PKCE, the consent screen, the exchange, refresh and revocation.

Ask for a family scope and the person picks which newsletter the token reaches; ask for account:read alone and it reaches no newsletter and reads only the account it belongs to.

Each operation lists the scopes a token must carry to call it. An operation that lists none takes any token.

Discover the URLs under flows at runtime from GET /.well-known/oauth-authorization-server rather than hardcoding them.

Flow type authorizationCode
Authorization URL https://usecommune.com/api/oauth/authorize
Token URL https://usecommune.com/api/oauth/token
Refresh URL https://usecommune.com/api/oauth/token
Scopes
  • content:read:

    Read articles, threads and the rest of what a newsletter publishes.

  • content:write:

    Create, edit and delete that content.

  • audience:read:

    Read subscribers, tags and segments, including email addresses.

  • audience:write:

    Add, tag and remove subscribers.

  • insights:read:

    Read engagement, delivery and growth figures.

  • insights:write:

    Write back an insight the newsletter owns.

  • sending:read:

    Read sends, schedules and delivery outcomes.

  • sending:write:

    Send an article, schedule one, and cancel a schedule.

  • settings:read:

    Read a newsletter's configuration, senders and domains.

  • settings:write:

    Change that configuration.

  • webhooks:read:

    Read event destinations and their delivery history.

  • webhooks:write:

    Create and remove event destinations.

  • account:read:

    Read the person the credential belongs to, and nothing about any newsletter.

Api key (http)

A Commune API key, sent as Authorization: Bearer <key>. A key is granted one or more newsletters and carries six permission families on each, every one of them none, read or write. An operation names the family and the level it needs.

A key is minted by a creator in Commune's settings: no flow, no consent screen, no expiry. That is the whole difference from oauth2. An operation that declares both accepts either credential, and what each may do is what it was granted.