communicate-so Authentication API

openapi: 3.2.0
info:
  title: Communicate So Authentication API
  version: 0.1.5
  description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: communicate-so-openapi.json, communicate-so-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.communicate.so/api/v1
  description: Canonical external base URL served through the Next.js /api/v1 rewrite.
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Authentication
paths:
  /oauth/token:
    post:
      operationId: createAccessToken
      summary: Exchange API-key client credentials for an access token
      description: Uses HTTP Basic authentication where the API key ID is the client ID and the one-time `ck_` token is the client secret. Requested scopes must be a subset of the API key scope ceiling.
      tags:
      - Authentication
      security:
      - clientCredentialsBasic: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                scope:
                  type: string
                  description: Space-delimited subset of `agents:read` and `chat:write`.
                resource:
                  type: string
                  format: uri
                  enum:
                  - https://app.communicate.so/api/v1
                  - https://app.communicate.so/mcp
                  default: https://app.communicate.so/api/v1
                  description: RFC 8707 resource audience. MCP tokens accept only `agents:read`.
      responses:
        '200':
          description: Short-lived scoped bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '400':
          description: Unsupported grant or invalid scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '401':
          description: Invalid or revoked client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '429':
          description: Token request rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
    servers:
    - url: https://app.communicate.so/api/v1
      description: Canonical external base URL served through the Next.js /api/v1 rewrite.
components:
  schemas:
    OAuthTokenResponse:
      type: object
      additionalProperties: false
      required:
      - access_token
      - token_type
      - expires_in
      - scope
      properties:
        access_token:
          type: string
        token_type:
          type: string
          enum:
          - Bearer
        expires_in:
          type: integer
          const: 3600
        scope:
          type: string
    OAuthErrorResponse:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    accountSession:
      type: apiKey
      in: cookie
      name: __Secure-better-auth.session_token
      description: Signed Better Auth session cookie for an HTTPS application origin. Credential management additionally requires verified email and fresh password proof on writes.
    localAccountSession:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: Signed session cookie used when the configured application auth origin is HTTP, such as local development.
    accountBearer:
      type: http
      scheme: bearer
      bearerFormat: Account credential
      description: Opaque user-bound `ca_` account credential. Each request checks live account scopes, verified email, expiry, revocation and the issuer session. Not a workspace `ck_` key or OAuth access token.
    clientCredentialsBasic:
      type: http
      scheme: basic
      description: Use the API key ID as the username and the one-time `ck_` API key token as the password.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client-credentials tokens bounded by the source API key scope ceiling.
      flows:
        clientCredentials:
          tokenUrl: https://app.communicate.so/api/v1/oauth/token
          scopes:
            agents:read: List agents in the authenticated workspace.
            chat:write: Create chat turns with an agent in the authenticated workspace.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Workspace API key token with the `ck_` prefix.
x-refined-from:
- communicate-so-openapi.json
- communicate-so-openapi.json