Clarifeye User Provisioning API

openapi: 3.2.0
info:
  title: Clarifeye Platform API — Full API Documentation User…
  description: 'Complete REST API reference for the Clarifeye Platform.


    Documents every endpoint exposed by the platform — the public surface plus

    the advanced surface: pipeline customization (extraction flows, pipeline

    runs, warehouse tables, document tag/metadata configuration), the pre-MCP

    AI surface (agent settings, playground conversations, conversation-scoped

    feedback views, notifications), and the impersonation header. New AI

    integrations should consume knowledge via MCP rather than the

    conversation/agent-settings endpoints documented here.


    ## Authentication

    All endpoints require authentication. Include the Authorization header in every request using either format:

    - `Authorization: Token `

    - `Authorization: Bearer `


    ## Service accounts and API keys

    Integrations authenticate with an **API key** of a **service account**:

    - `Authorization: Bearer ` (keys start with `cfk_`)


    A service account is an ordinary member (role `member`) of one organization that cannot log

    in. Organization admins create it and mint its keys on the organization''s *Service

    accounts* page (`/organizations/{id}/service-accounts/`, `/organization-api-keys/`), and

    give it access to knowledge stores with ordinary store permissions. A key is valid on every

    endpoint and acts as its service account: it reaches exactly the stores, with exactly the

    rights, the account was given. An account can hold several keys (each with its own name,

    optional expiry and revocation), so a key can be rotated without changing identity.


    A refused key answers **403** with one of: `Invalid API key.`, `API key revoked.`,

    `API key expired.`, `API key disabled.` (the service account is disabled).


    Any valid key may also call `POST /organizations/{id}/provision-user/` and

    `POST /organizations/{id}/deprovision-user/` for its own organization (the `{id}` in the

    path must be the key''s organization). The email domains these may pre-create accounts for

    are configured by Clarifeye on the organization (`allowed_provisioning_domains`).


    ## Impersonation


    Certain endpoints support user impersonation for creating or listing data on behalf of other users.

    This is useful for integrating external systems that need to attribute actions to specific users.


    **Header:** `X-Impersonate-Email`


    **Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (for a person, contact Clarifeye to enable it; org admins grant it to a service account on the organization''s Service accounts page)


    **Behavior:**

    - If the header is provided and the impersonator has the required permission, the action is performed as the target user

    - If the target user is not found, the request proceeds as the original authenticated user

    - If the target user does not have access to the project, the request proceeds as the original authenticated user

    - If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored


    **With an API key** the request fails instead (**403**) whenever impersonation cannot

    happen: missing permission, unknown target, target without access to the store, target that

    is itself a service account, or an endpoint outside a store. A key never silently acts as

    its own service account when impersonation was asked for.'
  version: 1.0.0
  contact:
    name: Clarifeye Support
servers:
- url: https://eu.app.clarifeye.ai/api/v1
  description: EU
- url: https://us.app.clarifeye.ai/api/v1
  description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: User Provisioning
  description: 'Pre-create and de-provision org users via an org-scoped API key

    (`Authorization: Bearer `). The organization is resolved from the key.'
paths:
  /organizations/{id}/provision-user/:
    parameters:
    - name: id
      in: path
      required: true
      description: UUID of the organization (must match the API key's org)
      schema:
        type: string
        format: uuid
    post:
      operationId: provisionOrganizationUser
      tags:
      - User Provisioning
      summary: Pre-create (or re-activate) an org user
      description: 'Pre-creates a user bound to this organization, with a verified primary email so a

        later SSO login links to it automatically. Idempotent: re-provisioning an existing

        member is a no-op (role/state unchanged). The email''s domain must be in the org''s

        `allowed_provisioning_domains`. The API key must belong to the organization in the path.

        Service accounts cannot be provisioned (400): they are managed on the organization''s

        Service accounts page.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum:
                  - member
                  - admin
                  default: member
      responses:
        '200':
          description: User provisioned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  email:
                    type: string
                    format: email
                  role:
                    type: string
                    enum:
                    - member
                    - admin
                  created:
                    type: boolean
        '400':
          description: Invalid payload, domain not allowed for this organization, or a service-account email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing/malformed/unknown API key, or the key's org does not match the path id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{id}/deprovision-user/:
    parameters:
    - name: id
      in: path
      required: true
      description: UUID of the organization (must match the API key's org)
      schema:
        type: string
        format: uuid
    post:
      operationId: deprovisionOrganizationUser
      tags:
      - User Provisioning
      summary: Remove an org user's membership
      description: 'Removes the user''s membership in this organization. If the user has no remaining

        memberships they are deactivated (blocking SSO login); otherwise their active

        organization is re-pointed. Returns `deprovisioned: false` if no such user. The

        API key must belong to the organization in the path. A service account cannot be

        deprovisioned (400): disable it on the Service accounts page instead.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: De-provisioning result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                  deprovisioned:
                    type: boolean
        '400':
          description: The email is a service account's.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing/malformed/unknown API key, or the key's org does not match the path id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{id}/provisioning-config/:
    parameters:
    - name: id
      in: path
      required: true
      description: UUID of the organization
      schema:
        type: string
        format: uuid
    get:
      operationId: getProvisioningConfig
      tags:
      - User Provisioning
      summary: Read the org's allowed provisioning domains (superuser only)
      responses:
        '200':
          description: Current configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisioningConfig'
        '403':
          description: Caller is not a superuser.
    patch:
      operationId: setProvisioningConfig
      tags:
      - User Provisioning
      summary: Set the org's allowed provisioning domains (superuser only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisioningConfig'
      responses:
        '200':
          description: Updated configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisioningConfig'
        '403':
          description: Caller is not a superuser.
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    ProvisioningConfig:
      type: object
      properties:
        allowed_provisioning_domains:
          type: array
          items:
            type: string
          description: Email domains that provisioning may pre-create accounts for.
      example:
        allowed_provisioning_domains:
        - loreal.com
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer <token>`. The token is either a user token / OAuth access

        token, or a service-account API key (`cfk_...`). A key is valid on every endpoint and

        acts as its service account, an organization member with per-store permissions.

        Refused keys answer 403 with `Invalid API key.`, `API key revoked.`,

        `API key expired.` or `API key disabled.`.

        '
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'
x-tagGroups:
- name: Extractors
  tags:
  - Object Extractors
  - Tag Extractors
  - Chunks Extractors
  - Parsing Extractors
  - Document Filter Extractors
  - Chunk Tag Filter Extractors
  - Document Tag Extractors
  - Tag Alerts Extractors
  - Object Alerts Extractors
  - Imported Object Extractors
x-provenance:
  method: harvested
  publisher: Clarifeye
  source: https://docs.clarifeye.ai/api-reference/openapi-full.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)