For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
LoginStart trialGet a demo
  • Welcome
    • Getting Started
    • Create an API Key
    • Pagination
    • Rate Limiting
    • No-Code Integrations
  • Webhooks
  • OAuth2
  • API Reference
LogoLogo
LoginStart trialGet a demo
On this page
  • Authorization Code Flow
  • Refreshing tokens
  • Token utilities
  • Available scopes

OAuth2

Implement OAuth2 authorization code flow for beehiiv integrations.
Was this page helpful?
Previous

Authorize

Next
Built with

For more information about registering an OAuth client, contact beehiiv Support.

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

1

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 (recommended for public clients)

Example:

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
2

Receive an authorization code

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

  • code
  • state (if provided)
3

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 (when using PKCE)

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

4

Call beehiiv APIs with the access token

Use the token as a bearer token in API requests:

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
  • posts:read, posts:write
  • publications:read, publications:write
  • referral_program:read, referral_program:write
  • segments:read, segments:write
  • tiers:read, tiers:write
  • webhooks:read, webhooks:write