openapi: 3.2.0
info:
  title: Hookbase Portal Tokens API
  version: 1.0.0
  description: Official OpenAPI 3.0 specification for the Hookbase webhook relay platform. Generated from the maintained Postman collection. Authenticate with an API key (whr_ prefix) as a Bearer token.
  contact:
    name: Hookbase
    url: https://www.hookbase.app
servers:
- url: https://api.hookbase.app
  description: Production
security:
- bearerAuth: []
tags:
- name: Portal Tokens
paths:
  /api/portal/webhook-applications/{webhookApplicationId}/tokens:
    post:
      tags:
      - Portal Tokens
      summary: Create Portal Token
      operationId: portal_tokens_create_portal_token
      parameters:
      - name: webhookApplicationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Mint a portal token that lets an application's users access the embeddable portal.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional. Token label (max 100).
                scopes:
                  type: array
                  items:
                    type: string
                  description: 'Optional. Scopes: read, write (default both).'
                expiresInDays:
                  type: integer
                  description: Optional. Lifetime in days (1–365, default 30).
                allowedIps:
                  type: array
                  items:
                    type: string
                  description: Optional. Restrict use to these IPs/CIDRs.
            example:
              name: Acme portal token
              scopes:
              - read
              - write
              expiresInDays: 30
              allowedIps:
              - 203.0.113.0/24
    get:
      tags:
      - Portal Tokens
      summary: List Portal Tokens
      operationId: portal_tokens_list_portal_tokens
      parameters:
      - name: webhookApplicationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: List active portal tokens for an application.
  /api/portal/webhook-applications/{webhookApplicationId}/magic-link:
    post:
      tags:
      - Portal Tokens
      summary: Create Portal Magic Link
      operationId: portal_tokens_create_portal_magic_link
      parameters:
      - name: webhookApplicationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Create a short-lived magic link that opens the portal without a stored token.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                expiresInMinutes:
                  type: integer
                  description: Optional. Link lifetime in minutes (1–1440, default 60).
                scopes:
                  type: array
                  items:
                    type: string
                  description: 'Optional. Scopes: read, write (default both).'
            example:
              expiresInMinutes: 60
              scopes:
              - read
              - write
  /api/portal/tokens/{portalTokenId}:
    delete:
      tags:
      - Portal Tokens
      summary: Revoke Portal Token
      operationId: portal_tokens_revoke_portal_token
      parameters:
      - name: portalTokenId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Revoke a portal token by id.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Hookbase API key with the whr_ prefix.