beehiiv

beehiiv Tokens API

The Tokens API from beehiiv — 4 operation(s) for tokens.

GitHub OpenAPI

Operations 4

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /oauth/token Exchange a code or refresh token for access · Create token #
Ask an LLM
“How do I turn an OAuth authorization code into an access token?”
“Can I refresh an expired access token with my refresh token?”
Tell an agent
Exchange authorization code {code} for an access token using grant type {grant_type}.
Get a new access token from refresh token {refresh_token} with grant type {grant_type}.
POST /oauth/revoke Revoke an access or refresh token · Revoke token #
Ask an LLM
“How do I revoke a token when a user disconnects my app?”
“Can I invalidate a refresh token instead of an access token?”
Tell an agent destructive · confirm first
Revoke token {token}.
Revoke {token} as a {token_type_hint}.
POST /oauth/introspect Check whether a token is active · Introspect token #
Ask an LLM
“Is a given OAuth token still valid?”
“What metadata can I learn about an arbitrary token I hold?”
Tell an agent
Introspect token {token} and tell me if it is active.
Check whether {token} is still a valid {token_type_hint}.
GET /oauth/token/info Get info about the current access token · Get token info #
Ask an LLM
“What scopes and expiry does the access token I'm calling with have?”
“When does my current bearer token expire?”
Tell an agent
Show metadata for the access token I'm using right now.
Tell me the scopes and expiry of my current bearer token.

Documentation

📖
Documentation
https://developers.beehiiv.com/oauth2
📖
Authentication
https://artifacts.apis.io/beehiiv/authentication/beehiiv-authentication.yml
📖
Documentation
https://developers.beehiiv.com/webhooks

Specifications

⚙
OpenAPI
https://artifacts.apis.io/beehiiv/openapi/beehiiv-tokens-api-openapi.yml
⚙
AsyncAPI
https://artifacts.apis.io/beehiiv/asyncapi/beehiiv-asyncapi.yml

Other Resources

🔗
OAuthScopes
https://artifacts.apis.io/beehiiv/scopes/beehiiv-scopes.yml
🔗
Webhooks
https://artifacts.apis.io/beehiiv/openapi/_original/beehiiv-webhook-events-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/beehiiv:beehiiv-tokens-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

beehiiv-tokens-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: OAuth2 Tokens API
  version: 1.0.0
servers:
- url: https://app.beehiiv.com
  description: Default
tags:
- name: Tokens
paths:
  /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'
components:
  schemas:
    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
    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__TokenType:
      type: string
      enum:
      - Bearer
      description: The token type returned by OAuth2 token endpoints.
      title: TokenType
    type__EmptyResponse:
      type: object
      properties: {}
      title: EmptyResponse
    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__TokenTypeHint:
      type: string
      enum:
      - access_token
      - refresh_token
      description: A hint about the type of token being sent.
      title: TokenTypeHint
    type__GrantType:
      type: string
      enum:
      - authorization_code
      - refresh_token
      description: The OAuth2 grant type.
      title: GrantType
    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__TokenApplication:
      type: object
      properties:
        uid:
          type: string
        name:
          type: string
      description: OAuth application metadata attached to token info responses.
      title: TokenApplication
x-provenance:
  method: harvested
  publisher: beehiiv
  source: https://developers.beehiiv.com/openapi/oauth2.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)