Lucid SCIM API

openapi: 3.0.3
info:
  title: Lucid SCIM API
  version: '1.0'
  description: The Lucid SCIM 2.0 API enables identity providers to automatically provision and deprovision
    users and groups in a Lucid account. Supports standard SCIM operations for user lifecycle management.
  contact:
    name: Lucid Developer Platform
    url: https://developer.lucid.co/
  x-documentation: https://developer.lucid.co/reference/overview-scim
x-harvest:
  harvested: '2026-08-01'
  method: searched
  source: https://lucid-developer-docs.readme.io/mcp
  note: 'Assembled operation-by-operation from Lucid''s own documentation MCP server (tools list-endpoints
    + get-endpoint), which returns verbatim OpenAPI 3.0.3 fragments out of the spec Lucid uploaded to
    its ReadMe hub (/branches/1.4/apis/lucid-scim-api.json). Paths, operations, parameters, request bodies,
    responses, components and securitySchemes are provider content, unmodified. Only the info block is
    ours: ReadMe''s per-endpoint fragments omit info, so title/description are copied verbatim from the
    provider''s own list-specs description for this spec.'
servers:
- url: https://users.lucid.app/scim/v2
tags:
- name: Users
  description: Endpoints that deal with users.
- name: Groups
  description: Endpoints that deal with org groups or teams (dependent on which bearer token is used).
- name: Schemas
  description: Endpoints that deal with lucid resource schemas.
- name: Service Provider Config
  description: Retrieve the SCIM service provider configuration, describing supported operations, authentication
    schemes, and bulk/filter capabilities.
security:
- Bearer: []
paths:
  /Users/{id}:
    get:
      summary: Get User
      description: Get a specific user on the account.
      operationId: getUser
      tags:
      - Users
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: ID of the Lucid user.
        example: lucid-1234
      - $ref: '#/paths/~1Users/get/parameters/3'
      - $ref: '#/paths/~1Users/get/parameters/4'
      responses:
        '200':
          description: OK. Returns a User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '404':
          description: Not Found. Occurs if the user was not found.
    put:
      summary: Modify User
      description: 'Modify an existing user. To deactivate a user, set the `active` field to `false`.

        '
      operationId: modifyUserPut
      tags:
      - Users
      parameters:
      - $ref: '#/paths/~1Users~1%7Bid%7D/get/parameters/0'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '200':
          description: OK. Returns the modified User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request. Occurs if request body syntax is incorrect.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '404':
          description: Not Found. Occurs if the user does not exist.
        '409':
          description: Conflict. Occurs if new username or email already exists.
    patch:
      summary: Modify User
      description: 'Modify an existing user. To deactivate a user, set the `active` field to `false`.

        '
      operationId: modifyUserPatch
      tags:
      - Users
      parameters:
      - $ref: '#/paths/~1Users~1%7Bid%7D/get/parameters/0'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - schemas
              - Operations
              properties:
                schemas:
                  type: array
                  items:
                    type: string
                  example:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                Operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserOperation'
      responses:
        '200':
          description: OK. Returns the modified User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request. Occurs if request body syntax is incorrect.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '404':
          description: Not Found. Occurs if the user does not exist.
        '409':
          description: Conflict. Occurs if new username or email already exists on account.
    delete:
      summary: Delete User
      description: '> ❗️ This is a hard delete. We recommend deactivating users instead of deleting them.
        To deactivate a user, use PUT or PATCH and set the active field to false.


        Delete a user from the account. Note that certain users cannot be deleted, such as account owners
        and default document owners.

        '
      operationId: deleteUser
      tags:
      - Users
      parameters:
      - $ref: '#/paths/~1Users~1%7Bid%7D/get/parameters/0'
      responses:
        '204':
          description: No Content. User was successfully deleted.
        '400':
          description: Bad Request. Occurs if an unexpected error prevents user deletion.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '404':
          description: Not Found. Occurs if the user does not exist.
        '409':
          description: Conflict. Occurs if the user cannot be deleted (e.g., account owner or default
            document owner).
  /Users:
    get:
      summary: Get All Users
      description: Gets all users on an account.
      operationId: getAllUsers
      tags:
      - Users
      parameters:
      - name: startIndex
        in: query
        required: false
        schema:
          type: number
        description: Index of the first user in the list to return (1 indexed).
        example: 1
      - name: count
        in: query
        required: false
        schema:
          type: number
        description: Quantity of users to return from this request.
        example: 100
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: "See SCIM spec and optimization details below:\n* The only operator currently supported\
          \ is eq\n* Filtered requests will result in a maximum of 10,000 users\n* While filtering should\
          \ technically work on every attribute of a user, it is a very slow process for non-optimized\
          \ attributes. We strongly recommend filtering only on the following optimized attributes whenever\
          \ possible:\n  * email / emails.value / workemail\n  * username / displayname\n  * externalid\n\
          \  * urn:ietf:params:scim:schemas:extension:lucid:1.0:User.productLicenses.<name>\n"
        example: email eq someEmail@example.com
      - name: attributes
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: 'Comma-separated list of attribute names to include in the response. The attribute
          id is always returned. Cannot be used with excludedAttributes.

          '
        example: userName,emails,active
      - name: excludedAttributes
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: 'Comma-separated list of attribute names to exclude from the response. The attribute
          id is always returned and cannot be excluded. Cannot be used with attributes.

          '
        example: groups,roles
      responses:
        '200':
          description: OK. Returns a JSON object containing a list of users. Deactivated users will not
            be included in the totalResults or the JSON payload of users returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllUsers'
        '400':
          description: Bad Request. Occurs if the filter parameter has invalid syntax or uses unsupported
            operators.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
    post:
      summary: Create User
      description: Create a new user.
      operationId: createUser
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: OK. Returns the created User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request. Occurs if request body syntax is incorrect.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '409':
          description: Conflict. if username or email already exists on the account.
        '424':
          description: Failed Dependency. Occurs if add-on license requires base license to be active.
  /Groups/{id}:
    get:
      summary: Get Group or Team
      description: Get a specific org group or team on the account.
      operationId: getGroup
      tags:
      - Groups
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: ID of the Lucid group.
        example: lucid-group-1234
      - $ref: '#/paths/~1Groups/get/parameters/3'
      - $ref: '#/paths/~1Groups/get/parameters/4'
      responses:
        '200':
          description: OK. Returns a group or team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
        '404':
          description: Not Found. Occurs if the group was not found.
    put:
      summary: Modify Group or Team
      description: Modify an existing org group or team.
      operationId: modifyGroupPut
      tags:
      - Groups
      parameters:
      - $ref: '#/paths/~1Groups~1%7Bid%7D/get/parameters/0'
      - $ref: '#/paths/~1Groups/get/parameters/3'
      - $ref: '#/paths/~1Groups/get/parameters/4'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateGroup'
      responses:
        '200':
          description: OK. Returns the modified group or team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
        '404':
          description: Not Found. Occurs if the group was not found.
        '409':
          description: Conflict. Occurs if the group name already exists on the account. Org group and
            team namespaces are distinct, though the latter includes archived teams.
    patch:
      summary: Modify Group or Team
      description: Modify an existing org group or team.
      operationId: modifyGroupPatch
      tags:
      - Groups
      parameters:
      - $ref: '#/paths/~1Groups~1%7Bid%7D/get/parameters/0'
      - $ref: '#/paths/~1Groups/get/parameters/3'
      - $ref: '#/paths/~1Groups/get/parameters/4'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                schemas:
                  type: array
                  items:
                    type: string
                  description: URIs identifying the SCIM schemas that describe this resource's attributes.
                  example:
                  - urn:ietf:params:scim:schemas:core:2.0:Group
                Operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/GroupOperation'
                  description: Type of operation being performed (add, remove, or replace).
      responses:
        '200':
          description: OK. Returns the modified group or team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request. Occurs if the request body syntax is incorrect.
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
        '404':
          description: Not Found. Occurs if the group was not found.
        '409':
          description: Conflict. Occurs if the group name already exists on the account. Org group and
            team namespaces are distinct, though the latter includes archived teams.
    delete:
      summary: Delete Group or Team
      description: Delete an existing org group or archive an existing team.
      operationId: deleteGroup
      tags:
      - Groups
      parameters:
      - $ref: '#/paths/~1Groups~1%7Bid%7D/get/parameters/0'
      responses:
        '204':
          description: No Content. Occurs if the delete was successful.
        '400':
          description: Bad Request. May occur if an org group still has members.
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
        '404':
          description: Not Found. Occurs if the group was not found.
  /Groups:
    get:
      summary: Get All Groups or Teams
      description: 'Gets all org groups or teams on an account. Supports pagination and filtering.

        '
      operationId: getAllGroups
      tags:
      - Groups
      parameters:
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Filter groups/teams using SCIM filter syntax. Only single filter queries are supported.
          Currently supports filtering by displayName (case-sensitive exact match).
        example: displayName eq "Engineering"
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 100
          minimum: 0
        description: Maximum number of groups/teams to return per page for pagination. Negative values
          are interpreted as 0.
        example: 50
      - name: startIndex
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        description: The 1-based index of the first result to return for pagination. Values less than
          1 are interpreted as 1.
        example: 1
      - name: attributes
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Comma-separated list of attribute names to return in the response. The attribute
          id is always returned. Available attributes are schemas, displayName, members, and meta. Cannot
          be used with excludedAttributes.
        example: displayName,members
      - name: excludedAttributes
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Comma-separated list of attribute names to exclude from the response. The attribute
          id is always returned and cannot be excluded. Can exclude schemas, displayName, members, or
          meta. Cannot be used with attributes.
        example: members
      responses:
        '200':
          description: OK. Returns a list of org groups or teams.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllGroups'
        '401':
          description: Unauthorized. Occurs if bearer token is invalid.
    post:
      summary: Create Group or Team
      description: Create a new org group or team, or restore a matching archived, closed team.
      operationId: createGroup
      tags:
      - Groups
      parameters:
      - $ref: '#/paths/~1Groups/get/parameters/3'
      - $ref: '#/paths/~1Groups/get/parameters/4'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateGroup'
      responses:
        '201':
          description: Created. Returns the created group or team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request. Occurs if the group was not created.
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
        '409':
          description: Conflict. Occurs if the group name already exists on the account.
  /Schemas/{id}:
    get:
      summary: Get Schema
      description: Get a specific Lucid resource schema.
      operationId: getSchema
      tags:
      - Schemas
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: ID of the Lucid resource schema to get.
        example: /v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group
      responses:
        '200':
          description: OK. Returns a Schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
        '404':
          description: Not Found. Occurs if the schema was not found.
  /Schemas:
    get:
      summary: Get All Schemas
      description: Gets all Lucid resource schemas.
      operationId: getAllSchemas
      tags:
      - Schemas
      responses:
        '200':
          description: OK. Returns a JSON object containing a list of Schemas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllSchemas'
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
  /ServiceProviderConfig:
    get:
      summary: Get Service Provider Config
      description: Get the service provider configuration.
      operationId: getServiceProviderConfig
      tags:
      - Service Provider Config
      responses:
        '200':
          description: OK. Returns a ServiceProviderConfig.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderConfig'
        '401':
          description: Unauthorized. Occurs if the bearer token is invalid.
components:
  schemas:
    UserBase:
      type: object
      description: Core attributes shared by all user representations.
      properties:
        schemas:
          type: array
          items:
            type: string
          description: URIs identifying the SCIM schemas that describe this resource's attributes.
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
          - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
        userName:
          type: string
          description: The user's username (usually their email).
          example: john-doe@example.com
        name:
          $ref: '#/components/schemas/Name'
        displayName:
          type: string
          description: The name that is displayed and represents the user (usually their email).
          example: john-doe@example.com
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        active:
          type: boolean
          description: Whether the user can authenticate to Lucid.
          example: false
        externalId:
          type: string
          description: An identifier for the user as defined by the provisioning client.
          example: external-123
        title:
          type: string
          description: The user's job title.
          example: Software Engineer
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: A list of phone numbers for the user. Currently only "work" type phone numbers
            are supported.
        meta:
          type: object
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: A list of administrative roles assigned to the user. Assigning a role to a user
            allows that user to perform administrative actions associated with that role.
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          $ref: '#/components/schemas/EnterpriseUserExtension'
    User:
      allOf:
      - $ref: '#/components/schemas/UserBase'
      - type: object
        properties:
          id:
            type: string
            description: Will be in the form "lucid-1234" with 1234 being the ID of the Lucid user.
            example: lucid-1234
          groups:
            type: array
            items:
              $ref: '#/components/schemas/UserGroup'
      description: A standard representation of a user.
    Name:
      type: object
      properties:
        formatted:
          type: string
          description: The users first and last name.
          example: John Doe
        givenName:
          type: string
          description: The user's first name.
          example: John
        familyName:
          type: string
          description: The user's last name.
          example: Doe
      description: An object representing a user's name in various formats.
    Email:
      type: object
      properties:
        value:
          type: string
          description: The user's email.
          example: john-doe@example.com
        type:
          type: string
          description: A label indicating the attribute's function (e.g., 'work' or 'home').
          example: work
        primary:
          type: boolean
          description: Used to determine the primary email of the emails given.
          example: true
      description: An object representing a user's email.
    PhoneNumber:
      type: object
      properties:
        value:
          type: string
          description: The phone number.
          example: +1-555-123-4567
        type:
          type: string
          description: The type of phone number (e.g., work, home, mobile). Only "work" type is currently
            supported.
          example: work
      description: An object representing a user's phone number.
    Role:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: Administrative role type.
          example: DocumentAdmin
          enum:
          - AccountAdmin
          - BillingAdmin
          - Developer
          - DocumentAdmin
          - EnterpriseShieldAdmin
          - TemplateAdmin
    EnterpriseUserExtension:
      type: object
      description: Enterprise extension attributes for the user.
      properties:
        costCenter:
          type: string
          description: The cost center associated with the user.
          example: CC-100
        organization:
          type: string
          description: The organization that the user belongs to.
          example: Engineering
        division:
          type: string
          description: The division that the user belongs to.
          example: Product Development
        department:
          type: string
          description: The department that the user belongs to.
          example: Backend Engineering
        manager:
          type: object
          description: The user's manager.
          properties:
            value:
              type: string
              description: The ID of the manager user. Will be in the form "lucid-1234" with 1234 being
                the ID of the Lucid user.
              example: lucid-5678
    UserGroup:
      type: object
      properties:
        value:
          type: string
          description: Id of group.
          example: lucid-group-1234
        display:
          type: string
          description: Display name of group.
          example: Group A
      description: An object representing a user's group.
    CreateUser:
      allOf:
      - $ref: '#/components/schemas/UserBase'
      - type: object
        required:
        - schemas
        - userName
        - emails
        properties:
          password:
            type: string
            example: password
            description: Passwords must be at least 8 characters in length.
    UserOperation:
      type: object
      required:
      - op
      properties:
        op:
          type: string
          enum:
          - add
          - remove
          - replace
          description: The operation to perform.
          example: add
        path:
          type: string
          description: Path to the field you want to change.
          example: roles
        value:
          oneOf:
          - type: boolean
          - type: string
          - type: object
          - type: array
            items: {}
          description: Value to be added/replaced.
          example:
          - value: Billing Admin
    GetAllUsers:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: The total number of users matching the query.
          example: 1
        startIndex:
          type: integer
          description: The index of the first user in the "Resources" list (for paginated results).
          example: 1
        itemsPerPage:
          type: integer
          description: The maximum number of users returned in the "Resources" list (for paginated results).
          example: 100
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: The list of users returned by the query.
    Group:
      type: object
      properties:
        id:
          type: string
          description: Will be in the form "lucid-group-1234" with 1234 being the ID of the Lucid org
            group or team.
          example: lucid-group-1234
        schemas:
          type: array
          items:
            type: string
          description: URIs identifying the SCIM schemas that describe this resource's attributes.
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        displayName:
          type: string
          description: The name of the org group or team.
          example: Group A
        members:
          type: array
          items:
            $ref: '#/components/schemas/Member'
          description: The users (and, for org groups, subgroups) that are members of this org group or
            team.
          example:
          - value: lucid-1433
            display: User 1
          - value: lucid-5678
            display: User 2
          - value: lucid-group-9012
            display: Subgroup A
        meta:
          type: object
    Member:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: The ID of the member. For org groups, this can be a user ID (e.g. "lucid-1234")
            or a subgroup ID (e.g. "lucid-group-5678"). For teams, only user IDs are supported.
          example: lucid-1433
        $ref:
          type: string
          description: The URI of the member. Points to /Users/{id} for user members, or for org groups,
            /Groups/{id} for subgroup members.
          example: https://users.lucid.app/scim/v2/Users/lucid-1433
        display:
          type: string
          description: The display name of the member (the user's name, or for org group subgroups, the
            subgroup's name).
          example: User 2
    CreateOrUpdateGroup:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: URIs identifying the SCIM schemas that describe this resource's attributes.
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        displayName:
          type: string
          description: The name of the org group or team.
          example: My Group
        members:
          type: array
          items:
            $ref: '#/components/schemas/Member'
    GroupOperation:
      type: object
      required:
      - op
      properties:
        op:
          type: string
          enum:
          - add
          - remove
          - replace
          description: The operation to perform.
          example: add
        path:
          type: string
          description: Path to the field you want to change.
          example: members
        value:
          oneOf:
          - type: string
          - type: array
            items: {}
          description: Value to be added/replaced.
          example:
          - value: lucid-1234
          - value: lucid-5678
    GetAllGroups:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: SCIM schema URIs for the list response.
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: The total number of org groups or teams matching the query (across all pages, not
            just the current page).
          example: 42
        startIndex:
          type: integer
          description: The 1-based index of the first result in the "Resources" list (for paginated results).
            Reflects the startIndex parameter sent in the request.
          example: 1
        itemsPerPage:
          type: integer
          description: The maximum number of results returned in the "Resources" list (for paginated results).
            Reflects the count parameter sent in the request.
          example: 100
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/Group'
          description: The list of org groups or teams returned by the query.
    Schema:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Schema
        id:
          type: string
          description: The id of the schema resource.
          example: urn:ietf:params:scim:schemas:core:2.0:Group
        name:
          type: string
          description: The name of the schema resource.
          example: Group
        description:
          type: string
          description: The description of the schema resource.
          example: A group of users
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        meta:
          type: object
    Attribute:
      description: An attribute definition for a SCIM schema resource. Complex attributes may contain
        subAttributes.
      allOf:
      - $ref: '#/components/schemas/SubAttribute'
      - type: object
        properties:
          subAttributes:
            type: array
            description: Defines nested attributes for complex attribute types.
            items:
              $ref: '#/components/schemas/SubAttribute'
    SubAttribute:
      type: object
      description: A leaf-level attribute definition. Like Attribute but without subAttributes, since
        sub-attributes cannot themselves be complex.
      properties:
        name:
          type: string
          description: The name of the attribute.
          example: id
        type:
          type: string
          enum:
          - string
          - boolean
          - decimal
          - integer
          - dateTime
          - reference
          - complex
          description: What the type of the attribute is.
          example: string
        multiValued:
          type: boolean
          description: Indicates whether the attribute can have multiple values.
          example: false
        description:
          type: string
          description: Description for the associated attribute.
          e

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucid/refs/heads/main/openapi/lucid-scim-api-openapi.yml