contentstack SCIM Users API

openapi: 3.2.0
info:
  title: Contentstack SCIM SCIM Users API
  description: The Contentstack SCIM API implements the System for Cross-domain Identity Management (SCIM 2.0) standard to enable automated user lifecycle management within a Contentstack organization. It allows Identity Providers (IdPs) to provision and deprovision users, manage group memberships, and synchronize user attributes between the IdP and Contentstack. This API is primarily used by enterprise organizations that manage Contentstack access through centralized identity management platforms such as Okta, Azure AD, or OneLogin. Group mappings in Contentstack allow IdP-managed groups to control role-based access within the CMS.
  version: '2.0'
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://auth-api.contentstack.com
  description: AWS North America Production Server
- url: https://eu-auth-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-auth-api.contentstack.com
  description: AWS Australia Production Server
- url: https://azure-na-auth-api.contentstack.com
  description: Azure North America Production Server
- url: https://azure-eu-auth-api.contentstack.com
  description: Azure Europe Production Server
- url: https://gcp-na-auth-api.contentstack.com
  description: GCP North America Production Server
- url: https://gcp-eu-auth-api.contentstack.com
  description: GCP Europe Production Server
security:
- bearerAuth: []
tags:
- name: SCIM Users
  description: SCIM user endpoints enable Identity Providers to provision, update, and deprovision user accounts within a Contentstack organization following the SCIM 2.0 User schema.
paths:
  /scim/v2.0/organizations/{organization_uid}/Users:
    get:
      operationId: listScimUsers
      summary: List SCIM users
      description: Retrieves all users in the organization following the SCIM 2.0 ListResponse format. Supports filtering by userName (email address) using the filter query parameter for user lookup during IdP sync operations.
      tags:
      - SCIM Users
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - name: filter
        in: query
        description: 'SCIM filter expression for searching users. Example: userName eq "user@example.com"'
        schema:
          type: string
      responses:
        '200':
          description: A SCIM ListResponse containing user resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createScimUser
      summary: Create a SCIM user
      description: Provisions a new user in the Contentstack organization via SCIM. The user is created with the attributes provided in the SCIM User resource and assigned to the organization's default role unless group mappings specify otherwise.
      tags:
      - SCIM Users
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUser'
      responses:
        '201':
          description: The newly provisioned SCIM user resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: A user with this userName already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimError'
  /scim/v2.0/organizations/{organization_uid}/Users/{user_id}:
    get:
      operationId: getScimUser
      summary: Get a SCIM user
      description: Retrieves the SCIM User resource for a specific user by their SCIM user ID within the organization.
      tags:
      - SCIM Users
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: The SCIM user resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceScimUser
      summary: Replace a SCIM user
      description: Fully replaces a SCIM user resource with the provided attributes. All attributes not included in the request will be cleared or reset to defaults following SCIM 2.0 PUT semantics.
      tags:
      - SCIM Users
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUser'
      responses:
        '200':
          description: The updated SCIM user resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateScimUser
      summary: Update a SCIM user
      description: Partially updates a SCIM user resource using SCIM 2.0 PATCH operations. Commonly used to activate or deactivate users by setting the active attribute, or to update specific profile attributes without replacing the entire resource.
      tags:
      - SCIM Users
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
      responses:
        '200':
          description: The updated SCIM user resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ScimPatchRequest:
      type: object
      description: A SCIM 2.0 PatchOp request for partial resource updates.
      properties:
        schemas:
          type: array
          description: SCIM schema URN identifying this as a PatchOp request.
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          description: List of PATCH operations to perform.
          items:
            $ref: '#/components/schemas/ScimPatchOperation'
    ScimListResponse:
      type: object
      description: A SCIM 2.0 ListResponse container for multi-resource responses.
      properties:
        schemas:
          type: array
          description: SCIM schema URNs identifying this as a ListResponse.
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Total number of resources matching the query.
        startIndex:
          type: integer
          description: 1-based index of the first result in this page.
        itemsPerPage:
          type: integer
          description: Number of results returned in this response.
        Resources:
          type: array
          description: Array of SCIM resource objects (Users or Groups).
          items:
            type: object
    ScimError:
      type: object
      description: A SCIM 2.0 error response.
      properties:
        schemas:
          type: array
          description: SCIM schema URN for error responses.
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:Error
        status:
          type: string
          description: HTTP status code as a string.
        detail:
          type: string
          description: Human-readable description of the error.
    ScimUser:
      type: object
      description: A SCIM 2.0 User resource representing a Contentstack user account.
      properties:
        schemas:
          type: array
          description: SCIM schema URNs for this resource.
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
        id:
          type: string
          description: SCIM-assigned unique identifier for the user.
        userName:
          type: string
          format: email
          description: The user's email address used as the primary unique identifier.
        name:
          type: object
          description: The user's name components.
          properties:
            givenName:
              type: string
              description: The user's first name.
            familyName:
              type: string
              description: The user's last name.
        emails:
          type: array
          description: List of email addresses for the user.
          items:
            type: object
            properties:
              value:
                type: string
                format: email
                description: The email address value.
              primary:
                type: boolean
                description: Indicates whether this is the primary email address.
        active:
          type: boolean
          description: Indicates whether the user account is active. Set to false to deprovision (deactivate) the user in Contentstack.
    ScimPatchOperation:
      type: object
      description: A single SCIM PATCH operation.
      required:
      - op
      properties:
        op:
          type: string
          description: The operation type.
          enum:
          - add
          - remove
          - replace
        path:
          type: string
          description: The attribute path to target for the operation.
        value:
          description: The value to apply for add or replace operations.
  responses:
    NotFound:
      description: The requested SCIM resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
    Unauthorized:
      description: The SCIM bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
    BadRequest:
      description: The SCIM request is malformed or contains invalid attribute values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      description: The SCIM user ID of the user within the organization.
      schema:
        type: string
    OrganizationUid:
      name: organization_uid
      in: path
      required: true
      description: The unique identifier of the Contentstack organization.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token from the Identity Provider client for SCIM authentication.
externalDocs:
  description: Contentstack SCIM API Documentation
  url: https://www.contentstack.com/docs/developers/apis/scim-api