ZenZap O Auth API

openapi: 3.2.0
info:
  title: Zenzap External Integration O Auth API
  description: API for external applications to integrate with Zenzap.
  version: 2.0.0
  contact:
    name: Zenzap Support
    url: https://zenzap.co/support
servers:
- url: https://api.zenzap.co
  description: Production server
security:
- bearerAuth: []
  hmacSignature: []
- oauth2ClientCredentials: []
tags:
- name: OAuth
  description: OAuth 2.0 `client_credentials` grant.
paths:
  /oauth/token:
    post:
      summary: Issue an OAuth access token
      description: 'Exchanges OAuth client credentials for a short-lived bearer access token.


        Only the **`client_credentials`** grant is supported on this endpoint. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) in your Zenzap admin console.


        **Client authentication**: either send `client_id` + `client_secret` in the form body, or use HTTP Basic Auth with the same values (`Authorization: Basic base64(clientId:clientSecret)`).


        **Scopes**: omit the `scope` field to receive a token with all scopes configured on the bot, or pass a space-separated subset to down-scope. Requesting a scope that the bot was not granted at creation will fail.


        **Token lifetime**: 1 hour. There is **no refresh token** — re-mint with the client credentials when the token expires.


        Tokens are JWTs bound to the issuing region and to the bot. They are validated on every request. See Authentication for the full reference.'
      operationId: issueOAuthToken
      tags:
      - OAuth
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
            examples:
              clientCredentialsBody:
                summary: Credentials in form body
                value:
                  grant_type: client_credentials
                  client_id: b@660e8400-e29b-41d4-a716-446655440003
                  client_secret: very-long-random-secret
              withScope:
                summary: Down-scoped request
                value:
                  grant_type: client_credentials
                  client_id: b@660e8400-e29b-41d4-a716-446655440003
                  client_secret: very-long-random-secret
                  scope: channel:list message:send
              basicAuth:
                summary: Credentials via HTTP Basic (omit client_id / client_secret in body)
                value:
                  grant_type: client_credentials
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
              example:
                access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                token_type: Bearer
                expires_in: 3600
                scope: channel:list message:send
        '400':
          description: Invalid request (missing parameters, unsupported grant type, or requested scopes not allowed for the client)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
              examples:
                unsupportedGrant:
                  summary: Unsupported grant type
                  value:
                    error: unsupported_grant_type
                    error_description: unsupported grant_type
                invalidGrant:
                  summary: Invalid client credentials or scope
                  value:
                    error: invalid_grant
                    error_description: invalid client credentials or scopes
        '401':
          description: Client authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
              example:
                error: invalid_client
                error_description: missing client_secret
components:
  schemas:
    OAuthTokenRequest:
      type: object
      required:
      - grant_type
      properties:
        grant_type:
          type: string
          enum:
          - client_credentials
          description: OAuth 2.0 grant type. Only `client_credentials` is supported.
        client_id:
          type: string
          description: The bot's OAuth `clientId` (returned when the bot was created or rotated). Omit if you authenticate via HTTP Basic Auth.
          example: b@660e8400-e29b-41d4-a716-446655440003
        client_secret:
          type: string
          description: The bot's OAuth `clientSecret`. Omit if you authenticate via HTTP Basic Auth.
          example: very-long-random-secret
        scope:
          type: string
          description: 'Space-separated list of OAuth scopes to request. Optional — if omitted, the issued token receives every scope the bot was granted at creation.

            Passing a scope the bot was not granted will fail with `invalid_grant`.

            '
          example: channel:list message:send
    OAuthTokenResponse:
      type: object
      required:
      - access_token
      - token_type
      - expires_in
      properties:
        access_token:
          type: string
          description: 'JWT bearer token. Pass as `Authorization: Bearer <access_token>` on every API request.

            '
        token_type:
          type: string
          enum:
          - Bearer
          description: Always `Bearer`.
        expires_in:
          type: integer
          format: int64
          description: Token lifetime in seconds (default 3600 = 1 hour).
          example: 3600
        scope:
          type: string
          description: Space-separated list of scopes granted to this token.
          example: channel:list message:send
    OAuthErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: RFC 6749 §5.2 error code.
          enum:
          - invalid_request
          - invalid_client
          - invalid_grant
          - unsupported_grant_type
          - invalid_scope
        error_description:
          type: string
          description: Human-readable explanation. Safe to surface to operators; not localized.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token for the request. Two flavors:


        - **Static API key** — pass your API key (the value returned as `apiKey` when the bot was created). Must be paired with `X-Signature` + `X-Timestamp` (the `hmacSignature` scheme).

        - **OAuth access token** — pass the JWT returned by `POST /oauth/token`. No signature headers are required.

        '
    hmacSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: 'HMAC-SHA256 signature for request verification. Required **only** when authenticating with a static API key. Omit when using an OAuth access token.

        '
    oauth2ClientCredentials:
      type: oauth2
      description: 'OAuth 2.0 `client_credentials` grant for API-key bots. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) to mint short-lived access tokens. See [Authentication](/api-reference/authentication) for details.


        Access tokens are bearer JWTs and expire after 1 hour. There is no refresh token — re-mint with the client credentials when the token expires.

        '
      flows:
        clientCredentials:
          tokenUrl: https://api.zenzap.co/oauth/token
          scopes:
            channel:list: List topics the bot belongs to
            channel:read: Read topic metadata
            channel:write: Create/update topics and manage members
            message:read: Read messages
            message:send: Send messages
            message:write: Edit / delete / mark-delivered / mark-read messages
            reaction:write: Add and remove reactions on messages
            task:read: Read tasks
            task:write: Create / update / delete tasks
            poll:write: Create polls and cast / retract votes
            member:read: List organization members
            updates:read: Long-poll for outbound events