Elaichi Group mapping API

openapi: 3.2.0
info:
  title: Elaichi Group mapping 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: Group mapping
paths:
  /group-mapping:
    get:
      operationId: listGroupMappings
      summary: List SCIM group → role mappings
      tags:
      - Group mapping
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - result
                - next_cursor
                - prev_cursor
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Group mapping id (`gmap_…`).
                        scim_group_id:
                          type: string
                          description: SCIM group from `GET /scim-group`.
                        role_ids:
                          type: array
                          maxItems: 1
                          items:
                            type: string
                          description: The single role (`role_…`) every member of that group receives.
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  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 SCIM group to role mappings, cursor-paginated. Requires `sso:view`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
    post:
      operationId: createGroupMapping
      summary: Create a group → role mapping
      tags:
      - Group mapping
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Group mapping id (`gmap_…`).
                  scim_group_id:
                    type: string
                    description: SCIM group from `GET /scim-group`.
                  role_ids:
                    type: array
                    maxItems: 1
                    items:
                      type: string
                    description: The single role (`role_…`) every member of that group receives.
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '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: 'Every member of the SCIM group receives these roles. The model is a UNION: mapped roles merge onto roles assigned manually through `PATCH /member/{userId}`, they do not replace them. Roles are recomputed for affected members immediately, and again on every SCIM membership change. Requires `sso:manage`. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scim_group_id
              properties:
                scim_group_id:
                  type: string
                  description: Group id from `GET /scim-group`.
                role_ids:
                  type: array
                  maxItems: 1
                  items:
                    type: string
                  description: At most one role (`role_…`). Defaults to empty (no mapping).
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
  /group-mapping/{id}:
    get:
      operationId: getGroupMapping
      summary: Get a group mapping
      tags:
      - Group mapping
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Group mapping id (`gmap_…`).
                  scim_group_id:
                    type: string
                    description: SCIM group from `GET /scim-group`.
                  role_ids:
                    type: array
                    maxItems: 1
                    items:
                      type: string
                    description: The single role (`role_…`) every member of that group receives.
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '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: Returns one SCIM group to role mapping. Requires `sso:view`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Group mapping id (`gmap_…`).
    patch:
      operationId: updateGroupMapping
      summary: Update a group mapping
      tags:
      - Group mapping
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Group mapping id (`gmap_…`).
                  scim_group_id:
                    type: string
                    description: SCIM group from `GET /scim-group`.
                  role_ids:
                    type: array
                    maxItems: 1
                    items:
                      type: string
                    description: The single role (`role_…`) every member of that group receives.
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '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: Updates a group mapping. **`role_ids` REPLACES the mapped role when present** — at most one role, since a member holds exactly one (two or more answers 400 `role_cardinality`). Members lose the old mapped role on their next recompute; manually assigned roles are untouched and always win. Requires `sso:manage`, and — because a mapping is a deferred grant applied with no actor present — you may only map a role whose permissions you hold yourself. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scim_group_id:
                  type: string
                role_ids:
                  type: array
                  maxItems: 1
                  items:
                    type: string
                  description: Replaces the mapped role; at most one.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Group mapping id (`gmap_…`).
    delete:
      operationId: deleteGroupMapping
      summary: Delete a group mapping
      tags:
      - Group mapping
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '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: Members of that group lose the mapped roles — and with them the permissions those carried — as soon as roles are recomputed. Manually assigned roles survive. Requires `sso:manage`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Group mapping id (`gmap_…`).
components:
  schemas:
    Success:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
    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
  parameters:
    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
    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
  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.