Elaichi Permissions API

openapi: 3.2.0
info:
  title: Elaichi Permissions API
  version: 0.1.0
  description: 'Control-plane HTTP API for Elaichi, the MCP control plane for SaaS teams. Authenticate with an organization API token (create one in the Elaichi app under Settings → API tokens) sent as a bearer token, plus the `X-Organization-Id` header on org-scoped routes; the MCP and OAuth endpoints use their own protocols. A few actions are deliberately not available to an API token and must be done by a person in the Elaichi app: managing API and SCIM tokens, creating an organization, approving an access request, deleting an organization, and changing the two-factor requirement. The operations concerned say so. Endpoints used only by the Elaichi app itself (sign-in, consent screens, browser redirects, inbound webhooks) are not documented.'
servers:
- url: https://api.elaichi.ai
  description: Production
tags:
- name: Permissions
paths:
  /permission:
    get:
      operationId: listPermissions
      summary: List permissions
      tags:
      - Permissions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - result
                - next_cursor
                - prev_cursor
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Permission name, e.g. `member:manage`. This is what goes on a role.
                        label:
                          type: string
                          description: Short human label.
                        description:
                          type: string
                        group:
                          type: string
                          description: Display section for a role editor, e.g. `Connectors`.
                        high_trust:
                          type: boolean
                          description: 'True when granting this permission lets its holder create something the organization’s own governance rules cannot bind afterwards. Today that is only `connector:create`: a connector is governed by who may use it, not by the destination it calls. Always present; show it wherever the permission is granted.'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  prev_cursor:
                    type:
                    - string
                    - 'null'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Lists the permission names a role may hold, with display labels. This is the source of truth for validating `permissions` on `POST /role` and `PATCH /role/{id}`. The catalog is per organization: it lists the permissions this organization may grant. Paged with `limit` and `cursor`; read every page for the whole catalog.'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
components:
  parameters:
    LimitQuery:
      name: limit
      in: query
      required: false
      description: Page size. Defaults to 50. Values above 200 are silently clamped to 200 rather than rejected; a value below 1, or a non-integer, is a 400. Ignored by the endpoints documented as unpaginated.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    OrganizationIdHeader:
      name: X-Organization-Id
      in: header
      required: false
      description: Target organization (`org_…`). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.
      schema:
        type: string
    CursorQuery:
      name: cursor
      in: query
      required: false
      description: Opaque cursor — pass the `next_cursor` from a previous response. Ignored by unpaginated endpoints.
      schema:
        type: string
  schemas:
    Error:
      type: object
      required:
      - error
      description: The Elaichi error envelope. The MCP OAuth endpoints under `/oauth` are the exception — they return RFC 6749 errors instead (see `OAuthError`).
      properties:
        error:
          type: object
          required:
          - message
          - code
          properties:
            message:
              type: string
              description: Human-readable. 5xx messages are deliberately generic.
            code:
              type: string
              description: Stable machine-readable code, e.g. `not_found`, `subscription_required`.
            details:
              description: Structured detail for codes that carry one, e.g. `toolboxes_need_resolution`.
            feature:
              type: string
              description: The gated feature, on entitlement failures.
            plan:
              type:
              - string
              - 'null'
              enum:
              - personal
              - gold
              - black
              - null
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session or API token
      description: '`Authorization: Bearer <token>` with an org-scoped API token (`elch_{org_id}_{64 hex}`), created in the Elaichi app under Settings → API tokens. The Elaichi app itself signs in with a session cookie, which is also accepted but is not meant for integrations. Two other credential families exist and are NOT interchangeable with this one: an MCP OAuth access token (`POST /mcp` only) and a SCIM token (`/scim/v2/*` only).'
    mcpOAuth:
      type: oauth2
      description: MCP OAuth access token, used only by `POST /mcp` — not interchangeable with `bearerAuth`. Discovered per RFC 9728/8414 at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`.
      flows:
        authorizationCode:
          authorizationUrl: https://api.elaichi.ai/oauth/authorize
          tokenUrl: https://api.elaichi.ai/oauth/token
          scopes:
            mcp:read: Anything you can already see in Elaichi. Never secret values. It can also ask an admin for access to something restricted for you.
            mcp:write: Create and change teams, roles, toolboxes, templates and connections, and share access.
            mcp:destructive: Permanently delete data and remove access in Elaichi. This cannot be undone.
            mcp:tools: Run tools from the toolboxes you choose next, deleting in your connected apps included. It can also ask an admin for access to something restricted for you.
            openid: That you are signed in, and the user ID we use for you. Nothing else.
            email: Your email address, and whether it is verified. Apps use this to check your domain.