openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts SCIM Groups 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 Groups
  description: SCIM group endpoints allow Identity Providers to manage group memberships in Contentstack, which map to role-based access control within the CMS.
paths:
  /scim/v2.0/organizations/{organization_uid}/Groups:
    get:
      operationId: listScimGroups
      summary: List SCIM groups
      description: Retrieves all groups in the organization following the SCIM 2.0 ListResponse format. Supports filtering by displayName for group lookup during IdP sync operations.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - name: filter
        in: query
        description: 'SCIM filter expression for searching groups. Example: displayName eq "Editors"'
        schema:
          type: string
      responses:
        '200':
          description: A SCIM ListResponse containing group resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createScimGroup
      summary: Create a SCIM group
      description: Creates a new group in the Contentstack organization via SCIM. Groups can be mapped to specific roles and stacks in Contentstack to control member access permissions.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
      responses:
        '201':
          description: The newly created SCIM group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scim/v2.0/organizations/{organization_uid}/Groups/{group_id}:
    get:
      operationId: getScimGroup
      summary: Get a SCIM group
      description: Retrieves the SCIM Group resource for a specific group by its SCIM group ID within the organization.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: The SCIM group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceScimGroup
      summary: Replace a SCIM group
      description: Fully replaces a SCIM group resource including all member assignments. Use this to synchronize the complete group membership from the IdP.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimGroup'
      responses:
        '200':
          description: The updated SCIM group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateScimGroup
      summary: Update a SCIM group
      description: Partially updates a SCIM group using SCIM 2.0 PATCH operations. Commonly used to add or remove individual members from the group without replacing the entire membership list.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
      responses:
        '200':
          description: The updated SCIM group resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteScimGroup
      summary: Delete a SCIM group
      description: Removes a SCIM group from the Contentstack organization. Members of the group retain their individual user accounts but lose the role permissions granted by the group mapping.
      tags:
      - SCIM Groups
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '204':
          description: Group deleted successfully.
        '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.
    ScimGroup:
      type: object
      description: A SCIM 2.0 Group resource representing a Contentstack user group.
      properties:
        schemas:
          type: array
          description: SCIM schema URNs for this resource.
          items:
            type: string
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        id:
          type: string
          description: SCIM-assigned unique identifier for the group.
        displayName:
          type: string
          description: The display name of the group.
        members:
          type: array
          description: List of user members in the group.
          items:
            type: object
            properties:
              value:
                type: string
                description: The SCIM user ID of the group member.
              display:
                type: string
                description: The display name of the group member.
  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
    GroupId:
      name: group_id
      in: path
      required: true
      description: The SCIM group ID of the group 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