Elaichi Org domains API

openapi: 3.2.0
info:
  title: Elaichi Org domains 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: Org domains
paths:
  /org-domain:
    get:
      operationId: listOrgDomains
      summary: List org domains
      tags:
      - Org domains
      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: Org domain id.
                        organization_id:
                          type: string
                          description: Owning organization (`org_…`).
                        domain:
                          type: string
                          description: DNS name, lowercased (e.g. `acme.com`).
                        verified:
                          type: boolean
                        verification_record:
                          type:
                          - string
                          - 'null'
                          description: The exact DNS TXT value to publish. Present until the domain is verified, then null — the token is of no further use.
                        default_role_id:
                          type:
                          - string
                          - 'null'
                          description: Role (`role_…`) explicitly configured for people who join through this domain, or null to track the default. Org Owner is refused here. Read `effective_default_role_id` to learn what a join actually grants.
                        effective_default_role_id:
                          type:
                          - string
                          - 'null'
                          description: 'Server-computed: the role accepting this verified domain offer (`GET /domain-join`) really grants. Equals `default_role_id` when that is set and the role still exists; otherwise the **Member** system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. `null` means even that fallback is missing, so accepting the offer fails rather than seating anyone.'
                        sso_connection_id:
                          type:
                          - string
                          - 'null'
                          description: Linked SSO connection (`sso_…`).
                        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 domains this organization has claimed, verified or not, cursor-paginated. Requires `org:manage` or `sso:view`. Claiming, verifying, editing and removing a domain all require `org:manage`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
    post:
      operationId: createOrgDomain
      summary: Claim org domain
      tags:
      - Org domains
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Org domain id.
                  organization_id:
                    type: string
                    description: Owning organization (`org_…`).
                  domain:
                    type: string
                    description: DNS name, lowercased (e.g. `acme.com`).
                  verified:
                    type: boolean
                  verification_record:
                    type:
                    - string
                    - 'null'
                    description: The exact DNS TXT value to publish. Present until the domain is verified, then null — the token is of no further use.
                  default_role_id:
                    type:
                    - string
                    - 'null'
                    description: Role (`role_…`) explicitly configured for people who join through this domain, or null to track the default. Org Owner is refused here. Read `effective_default_role_id` to learn what a join actually grants.
                  effective_default_role_id:
                    type:
                    - string
                    - 'null'
                    description: 'Server-computed: the role accepting this verified domain offer (`GET /domain-join`) really grants. Equals `default_role_id` when that is set and the role still exists; otherwise the **Member** system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. `null` means even that fallback is missing, so accepting the offer fails rather than seating anyone.'
                  sso_connection_id:
                    type:
                    - string
                    - 'null'
                    description: Linked SSO connection (`sso_…`).
                  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: Claims a DNS name for this organization. The response carries `verification_record` — publish that exact TXT value, then call `POST /org-domain/{id}/verify`. Unverified domains grant nothing. Requires `org: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:
              - domain
              properties:
                domain:
                  type: string
                  description: A valid DNS name, e.g. `acme.com`. Lowercased.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
  /org-domain/{id}:
    patch:
      operationId: patchOrgDomain
      summary: Update org domain defaults
      tags:
      - Org domains
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Org domain id.
                  organization_id:
                    type: string
                    description: Owning organization (`org_…`).
                  domain:
                    type: string
                    description: DNS name, lowercased (e.g. `acme.com`).
                  verified:
                    type: boolean
                  verification_record:
                    type:
                    - string
                    - 'null'
                    description: The exact DNS TXT value to publish. Present until the domain is verified, then null — the token is of no further use.
                  default_role_id:
                    type:
                    - string
                    - 'null'
                    description: Role (`role_…`) explicitly configured for people who join through this domain, or null to track the default. Org Owner is refused here. Read `effective_default_role_id` to learn what a join actually grants.
                  effective_default_role_id:
                    type:
                    - string
                    - 'null'
                    description: 'Server-computed: the role accepting this verified domain offer (`GET /domain-join`) really grants. Equals `default_role_id` when that is set and the role still exists; otherwise the **Member** system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. `null` means even that fallback is missing, so accepting the offer fails rather than seating anyone.'
                  sso_connection_id:
                    type:
                    - string
                    - 'null'
                    description: Linked SSO connection (`sso_…`).
                  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 the defaults of a claimed org domain. Merge-patch: omit a field to leave it alone, send `null` to clear it. `default_role_id` is the role granted when someone accepts the domain offer — Org Owner is refused, since that would auto-elevate anyone with an address on the domain. `sso_connection_id` must name an SSO connection in this organization. Requires `org: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
              properties:
                default_role_id:
                  type:
                  - string
                  - 'null'
                  description: Role id (`role_…`), or null to clear.
                sso_connection_id:
                  type:
                  - string
                  - 'null'
                  description: SSO connection id (`sso_…`), or null to unlink.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Org domain id.
    delete:
      operationId: deleteOrgDomain
      summary: Delete org domain
      tags:
      - Org domains
      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: 'Deletes a claimed org domain. Irreversible: the claim, its verification and any domain-join offer or SSO routing it provided are gone, and re-claiming requires publishing a fresh TXT record. Existing members are unaffected. Requires `org:manage`.'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Org domain id.
  /org-domain/{id}/verify:
    post:
      operationId: verifyOrgDomain
      summary: Verify an org domain
      tags:
      - Org domains
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    id:
                      type: string
                      description: Org domain id.
                    organization_id:
                      type: string
                      description: Owning organization (`org_…`).
                    domain:
                      type: string
                      description: DNS name, lowercased (e.g. `acme.com`).
                    verified:
                      type: boolean
                    verification_record:
                      type:
                      - string
                      - 'null'
                      description: The exact DNS TXT value to publish. Present until the domain is verified, then null — the token is of no further use.
                    default_role_id:
                      type:
                      - string
                      - 'null'
                      description: Role (`role_…`) explicitly configured for people who join through this domain, or null to track the default. Org Owner is refused here. Read `effective_default_role_id` to learn what a join actually grants.
                    effective_default_role_id:
                      type:
                      - string
                      - 'null'
                      description: 'Server-computed: the role accepting this verified domain offer (`GET /domain-join`) really grants. Equals `default_role_id` when that is set and the role still exists; otherwise the **Member** system role, which is what the join falls back to both when nothing is configured and when the configured role has since been deleted. `null` means even that fallback is missing, so accepting the offer fails rather than seating anyone.'
                    sso_connection_id:
                      type:
                      - string
                      - 'null'
                      description: Linked SSO connection (`sso_…`).
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
                - type: object
                  properties:
                    verified:
                      type: boolean
                      description: Outcome of this attempt.
                    detail:
                      type:
                      - string
                      - 'null'
                      description: Why verification failed, when it did.
        '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: Verifies a claimed org domain. Runs the DNS TXT challenge now. Idempotent and safe to poll. Returns the domain plus `detail`, which explains a failed lookup (`detail` appears only on this response). Requires `org: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: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Org domain id.
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.