> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.beehiiv.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server.

> **Warning**
>
> For more information about registering an OAuth client, contact [beehiiv Support](https://support.beehiiv.com/hc/en-us).

For integrations looking to integrate more seamlessly with beehiiv, the beehiiv API supports the standard OAuth2 authorization code flow.

OAuth2 endpoints are served under the `/oauth` namespace on the app domain (for example, `https://app.beehiiv.com/oauth/...`).

This guide will walk you through the steps to implement the OAuth2 authorization code flow for your integration.

## Authorization Code Flow

### Redirect the user to authorize your app

Send users to `GET /oauth/authorize` with:

* `client_id`
* `redirect_uri`
* `response_type=code`
* `scope` (space-delimited)
* `state` (recommended for CSRF protection)
* `code_challenge` and `code_challenge_method` (required for public clients)

Example:

```text
https://app.beehiiv.com/oauth/authorize?client_id=WDgKDt_bHOXUfWRhGf2ovKZmFHQ9r_Erd01IPmz_boc&redirect_uri=http%3A%2F%2Flocalhost%3A3008%2Fcallback&response_type=code&scope=posts%3Aread&state=12345678
```

### Receive an authorization code

After login and consent, beehiiv redirects to your `redirect_uri` with:

* `code`
* `state` (if provided)

### Exchange the code for tokens

Call `POST /oauth/token` with `application/x-www-form-urlencoded` body:

* `grant_type=authorization_code`
* `code`
* `redirect_uri`
* `client_id`
* `client_secret` (confidential clients)
* `code_verifier` (required for public clients)

The response contains `access_token`, `token_type`, `expires_in`, and `refresh_token` (when available).

### Call beehiiv APIs with the access token

Use the token as a bearer token in API requests:

```text
Authorization: Bearer <access_token>
```

## Refreshing tokens

Use `POST /oauth/token` with:

* `grant_type=refresh_token`
* `refresh_token`
* `client_id`
* `client_secret` (confidential clients)

## Token utilities

* `POST /oauth/revoke` revokes access or refresh tokens.
* `POST /oauth/introspect` checks token activity and metadata.
* `GET /oauth/token/info` returns metadata for the current bearer token.

## Available scopes

Each scope maps to a resource type (for example, `posts:*` scopes apply to posts endpoints).

Scope permission levels map to endpoint actions:

* `:read` permits read actions (for example, `GET` requests).
* `:write` is required for mutating actions (for example, `POST`, `PUT`, and `DELETE` requests).

Default scope:

* `identify:read`

Optional scopes:

* `automations:read`, `automations:write`
* `custom_fields:read`, `custom_fields:write`
* `subscriptions:read`, `subscriptions:write`
* `polls:read`, `polls:write`
* `podcasts:read`, `podcasts:write`
* `posts:read`, `posts:write`
* `publication_fields:read`, `publication_fields:write`
* `publications:read`, `publications:write`
* `referral_program:read`, `referral_program:write`
* `segments:read`, `segments:write`
* `tiers:read`, `tiers:write`
* `webhooks:read`, `webhooks:write`