beehiiv
beehiiv OAuth2 API

The beehiiv OAuth2 authorization surface — authorization-code flow with PKCE, plus token creation, refresh, revocation, introspection and token-info endpoints. Published by beehiiv as a separate OpenAPI 3.1 document from the API reference, and served on the app domain rather than the API domain.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: OAuth2
  version: 1.0.0
paths:
  /oauth/authorize:
    get:
      operationId: authorize
      summary: Authorize
      description: Starts the OAuth2 authorization code flow. This endpoint redirects the user to login and consent (if needed), then redirects back to your `redirect_uri` with a `code` and `state`.
      tags:
      - Authorizations
      parameters:
      - name: client_id
        in: query
        description: The OAuth application client ID (`uid`).
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        description: Must exactly match one of the app's configured redirect URIs.
        required: true
        schema:
          type: string
      - name: response_type
        in: query
        description: Must be `code` for the authorization code flow.
        required: true
        schema:
          type: string
      - name: scope
        in: query
        description: Space-delimited list of requested scopes.
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: Opaque value returned to your callback for CSRF protection.
        required: false
        schema:
          type: string
      - name: code_challenge
        in: query
        description: PKCE code challenge. Required for public clients.
        required: false
        schema:
          type: string
      - name: code_challenge_method
        in: query
        description: PKCE challenge method (`plain` or `S256`). Required for public clients when using PKCE.
        required: false
        schema:
          $ref: '#/components/schemas/type_:CodeChallengeMethod'
      responses:
        '302':
          description: Redirect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:EmptyResponse'
        '400':
          description: The request is invalid or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
        '401':
          description: Client authentication failed or the token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
  /oauth/token:
    post:
      operationId: token
      summary: Create token
      description: Exchanges an authorization code for an access token, or exchanges a refresh token for a new access token. Send parameters as application/x-www-form-urlencoded.
      tags:
      - Tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:TokenResponse'
        '400':
          description: The request is invalid or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
        '401':
          description: Client authentication failed or the token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  $ref: '#/components/schemas/type_:GrantType'
                  description: authorization_code or refresh_token.
                code:
                  type: string
                  description: Authorization code returned from /oauth/authorize.
                redirect_uri:
                  type: string
                  description: Must match the redirect URI used in the authorization request.
                client_id:
                  type: string
                  description: OAuth application client ID (uid).
                client_secret:
                  type: string
                  description: Required for confidential clients.
                refresh_token:
                  type: string
                  description: Refresh token returned from a previous token exchange.
                code_verifier:
                  type: string
                  description: PKCE code verifier. Required for public clients.
              required:
              - grant_type
  /oauth/revoke:
    post:
      operationId: revoke
      summary: Revoke token
      description: Revokes an access token or refresh token. Send parameters as `application/x-www-form-urlencoded`.
      tags:
      - Tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:EmptyResponse'
        '401':
          description: Client authentication failed or the token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
        '403':
          description: The authenticated client or token is not allowed to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The access or refresh token to revoke.
                token_type_hint:
                  $ref: '#/components/schemas/type_:TokenTypeHint'
                  description: Optional hint to help the server process the token faster.
                client_id:
                  type: string
                  description: OAuth application client ID (`uid`).
                client_secret:
                  type: string
                  description: Required for confidential clients.
              required:
              - token
  /oauth/introspect:
    post:
      operationId: introspect
      summary: Introspect token
      description: Returns whether a token is active and metadata about the token. Send parameters as `application/x-www-form-urlencoded`.
      tags:
      - Tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:IntrospectionResponse'
        '400':
          description: The request is invalid or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
        '401':
          description: Client authentication failed or the token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The access or refresh token to introspect.
                token_type_hint:
                  $ref: '#/components/schemas/type_:TokenTypeHint'
                  description: Optional hint to help the server process the token faster.
                client_id:
                  type: string
                  description: OAuth application client ID (`uid`).
                client_secret:
                  type: string
                  description: Required for confidential clients.
              required:
              - token
  /oauth/token/info:
    get:
      operationId: token-info
      summary: Get token info
      description: Returns metadata for the current access token.
      tags:
      - Tokens
      parameters:
      - name: Authorization
        in: header
        description: Bearer access token (`Bearer <access_token>`).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:TokenInfoResponse'
        '401':
          description: Client authentication failed or the token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:OAuthError'
servers:
- url: https://app.beehiiv.com
  description: Default
components:
  schemas:
    type_:CodeChallengeMethod:
      type: string
      enum:
      - plain
      - S256
      description: The PKCE code challenge method.
      title: CodeChallengeMethod
    type_:EmptyResponse:
      type: object
      properties: {}
      title: EmptyResponse
    type_:OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        error_uri:
          type: string
        state:
          type: string
      required:
      - error
      description: Standard OAuth2 error response.
      title: OAuthError
    type_:GrantType:
      type: string
      enum:
      - authorization_code
      - refresh_token
      description: The OAuth2 grant type.
      title: GrantType
    type_:TokenType:
      type: string
      enum:
      - Bearer
      description: The token type returned by OAuth2 token endpoints.
      title: TokenType
    type_:TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          $ref: '#/components/schemas/type_:TokenType'
        expires_in:
          type: integer
        refresh_token:
          type: string
        scope:
          type: string
        created_at:
          type: integer
      required:
      - access_token
      - token_type
      - expires_in
      - created_at
      description: Access token response from `/oauth/token`.
      title: TokenResponse
    type_:TokenTypeHint:
      type: string
      enum:
      - access_token
      - refresh_token
      description: A hint about the type of token being sent.
      title: TokenTypeHint
    type_:IntrospectionResponse:
      type: object
      properties:
        active:
          type: boolean
        scope:
          type: string
        client_id:
          type: string
        token_type:
          $ref: '#/components/schemas/type_:TokenType'
        exp:
          type: integer
        iat:
          type: integer
        nbf:
          type: integer
        sub:
          type: string
        aud:
          type: string
        iss:
          type: string
        jti:
          type: string
      required:
      - active
      description: RFC 7662 token introspection response.
      title: IntrospectionResponse
    type_:TokenApplication:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
      description: OAuth application metadata attached to token info responses.
      title: TokenApplication
    type_:TokenInfoResponse:
      type: object
      properties:
        resource_owner_id:
          type: string
        scope:
          type: string
        expires_in_seconds:
          type: integer
        application:
          $ref: '#/components/schemas/type_:TokenApplication'
        created_at:
          type: integer
      description: Metadata for the current access token.
      title: TokenInfoResponse
beehiiv OAuth2 API

Documentation

Specifications

Other Resources

OpenAPI Specification
