openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts SCIM Users API
  description: The Contentstack Analytics API provides access to usage and performance metrics for CMS, Launch, and Automate products within a Contentstack organization. Developers can retrieve analytics data programmatically to build custom dashboards, monitor content delivery performance, and track platform usage against plan limits. The API returns structured data suitable for aggregation with external analytics and business intelligence tools. Access is restricted to organization Owners and Admins. Requests use async job-based processing where initial POST calls queue the job and a subsequent GET call retrieves the results.
  version: v2
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com
  description: AWS Australia Production Server
security:
- bearerAuth: []
- authtokenAuth: []
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.
    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.
    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.
  responses:
    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'
    NotFound:
      description: The requested SCIM resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimError'
  parameters:
    OrganizationUid:
      name: organization_uid
      in: path
      required: true
      description: The unique identifier of the Contentstack organization.
      schema:
        type: string
    UserId:
      name: user_id
      in: path
      required: true
      description: The SCIM user ID of the user within the organization.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (M2M) with analytics access.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken. Only organization Owners and Admins can access analytics.
externalDocs:
  description: Contentstack Analytics API Documentation
  url: https://www.contentstack.com/docs/developers/apis/analytics-api