Authentication

Clients should authenticate by passing the token key in the Authorization HTTP header, prepended with the string Token (note the trailing space!).

For example, if your token was 401f7ac837da42b97f613d789819ff93537bee6a, your headers may look like this.

headers = {
    'Authorization': 'Token 401f7ac837da42b97f613d789819ff93537bee6a'
}

You can manage your API keys at API → Keys.

You can create as many API keys as you need. This is useful when you have different integrations that need different levels of access:

• A Zapier workflow that adds new subscribers might only need write access to subscribers
• An analytics dashboard might only need read access to emails and subscribers
• A custom script that sends emails might need sending access but nothing else

Each key can have its own label (like "Zapier - new subscribers" or "Internal dashboard") so you can keep track of what each one is for. If one integration is compromised or you stop using it, you can delete or regenerate just that key without affecting your other integrations.

Each API key can be configured with independent permissions for different parts of the API:

Each permission can be set to:

• write — full access to create, update, and delete
• read — can view but not modify
• none — no access

If you attempt an operation that your API key doesn't have permission for, you'll receive a 403 Forbidden response.

If you're using the API to manage multiple newsletters, you can pass the Buttondown-Context header to specify the newsletter you want to access.

Consider the following example, in which a single platform account manages multiple newsletters. Each newsletter has its own API key in addition to the platform account's API key:

flowchart TD
    A[sheinhardt] -->|owns| B[sheinhardt_pt]
    A[sheinhardt] -->|owns| C[sheinhardt_fr]
    A[sheinhardt] -->|owns| D[sheinhardt_de]
    A[sheinhardt] -->|owns| E[sheinhardt_en]

    subgraph A[sheinhardt]
       api_key_111
    end

    subgraph B[sheinhardt_pt]
       api_key_111_b
    end

    subgraph C[sheinhardt_fr]
       api_key_111_c
    end

    subgraph D[sheinhardt_de]
       api_key_111_d
    end

    subgraph E[sheinhardt_en]
       api_key_111_e
    end

The platform could programmatically access each newsletter's API key and pass it through, but this is clumsy and onerous. Instead, you can pass the Buttondown-Context header to specify the newsletter you want to access:

headers = {
    'Authorization': 'Token api_key_111',
    'Buttondown-Context': 'sheinhardt_pt'
}