openapi: 3.1.0
info:
  title: Ironclad OAuth 2.0 Authorization Groups API
  description: Documentation for Ironclad's OAuth 2.0 Implementation. More details on the [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749).
  version: '1'
  contact:
    name: Ironclad Support
    email: support@ironcladapp.com
servers:
- url: https://na1.ironcladapp.com/oauth
  description: Production server
- url: https://eu1.ironcladapp.com/oauth
  description: EU Production server
- url: https://demo.ironcladapp.com/oauth
  description: Demo server
tags:
- name: Groups
  description: Documentation on SCIM Groups.
paths:
  /Groups:
    get:
      summary: List all Groups
      description: "Documentation on listing Groups via SCIM. \n\n**OAuth Scope required:** `scim.groups.readGroups`"
      operationId: retrieve-all-groups
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Count'
      - name: filter
        in: query
        description: Filters for identifying subsets of groups. Filters must comply with the SCIM protocol's convention. For more details, see SCIM [RFC 7644 Section 3.4.2.2](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2).
        example: displayName eq "Legal Ops Group"
        schema:
          type: string
      - $ref: '#/components/parameters/ExcludedAttributes'
      responses:
        '200':
          $ref: '#/components/responses/GroupsResponse200'
        '400':
          $ref: '#/components/responses/GroupFilterResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
    post:
      summary: Create a Group
      description: "Documentation on creating a Group via SCIM. \n\n**OAuth Scope required:** `scim.groups.createGroups`"
      operationId: create-a-group
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        $ref: '#/components/requestBodies/GroupCreateRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/GroupResponse201'
        '400':
          $ref: '#/components/responses/GroupResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '409':
          $ref: '#/components/responses/AlreadyExistsResponse409'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
  /Groups/{groupId}:
    get:
      summary: Retrieve a Group
      description: "Documentation on accessing a Group via SCIM. \n\n**OAuth Scope required:** `scim.groups.readGroups`"
      operationId: retrieve-a-group
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/GroupId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      responses:
        '200':
          $ref: '#/components/responses/GroupResponse200'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
    patch:
      summary: Update a Group
      description: "Documentation on updating a Group via SCIM. This includes updating group membership. \n\n**OAuth Scope required:** `scim.groups.updateGroups`"
      operationId: update-group-membership
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/GroupId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - schemas
              - Operations
              properties:
                schemas:
                  type: array
                  default:
                  - urn:ietf:params:scim:api:messages:2.0:PatchOp
                  items:
                    type: string
                Operations:
                  type: array
                  description: Operations for updating groups. See snippets below for more details.
                  items:
                    properties:
                      op:
                        type: string
                        description: '"add" or "remove"'
                      path:
                        type: string
                        default: members
                      value:
                        type: array
                        description: An array of User Ids. User Ids can be found by filtering results from the Retrieve all Users endpoint.
                        items:
                          properties:
                            value:
                              type: string
                              description: The unique id of the user. User Ids can be found by filtering the Retrieve all Users endpoint.
                          required:
                          - value
                          type: object
                    required:
                    - op
                    - path
                    type: object
      responses:
        '200':
          $ref: '#/components/responses/GroupResponse200'
        '204':
          $ref: '#/components/responses/GroupResponse204'
        '400':
          $ref: '#/components/responses/GroupResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
    put:
      summary: Replace a Group
      description: "Documentation on replacing a Group via SCIM. \n\n**OAuth Scope required:** `scim.groups.updateGroups`"
      operationId: replace-a-group
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/GroupId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        $ref: '#/components/requestBodies/GroupCreateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/GroupResponse200'
        '400':
          $ref: '#/components/responses/GroupResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
    delete:
      summary: Delete a Group
      description: "Documentation on deleting a Group via SCIM. \n\n**OAuth Scope required:** `scim.groups.deleteGroups`"
      operationId: delete-a-group
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/GroupId'
      responses:
        '204':
          $ref: '#/components/responses/GroupResponse204'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Groups
components:
  responses:
    GroupFilterResponse400:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              schema:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '400'
              scimType:
                type: string
                description: The SCIM detail error keyword.
                example: invalidFilter
              detail:
                type: string
                description: A detailed human-readable message.
                example: 'No matching schema for attribute: legalName'
    GroupResponse200:
      description: 200 OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GroupResponseObject'
    ForbiddenResponse403:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              schemas:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '403'
    GroupResponse204:
      description: 204 No Content
    GroupResponse400:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              schemas:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '400'
              scimType:
                type: string
                description: The SCIM detail error keyword.
                example: invalidValue
              detail:
                type: string
                description: A detailed human-readable message.
                example: 'Invalid value at displayName: 123'
    GroupsResponse200:
      description: 200 OK
      content:
        application/json:
          schema:
            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 groups that match this filter. This may be larger than the number of groups in this page, in which case pagination may be used to retrieve the next page of results.
                example: 2
                default: 0
              Resources:
                type: array
                description: The current page of user results.
                items:
                  $ref: '#/components/schemas/GroupResponseObject'
              startIndex:
                type: integer
                description: The 1-based index of the first result in the current set of list results.
                example: 1
                default: 0
              itemsPerPage:
                type: integer
                description: Specifies the maximum number of resources that can be returned in a single page of results.
                example: 25
                default: 0
    NotFoundResponse404:
      description: 404 Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              schemas:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '404'
              detail:
                type: string
                description: A detailed human-readable message.
                example: Resource 6643ce2e22daa40f80025aee not found
    AlreadyExistsResponse409:
      description: 409 Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              schemas:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '409'
    ServerErrorResponse500:
      description: 500 Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              schemas:
                type: array
                items:
                  type: string
                  example: urn:ietf:params:scim:api:messages:2.0:Error
              status:
                type: string
                description: The HTTP status code expressed as a string.
                example: '500'
              detail:
                type: string
                description: A detailed human-readable message.
                example: Internal server error
    GroupResponse201:
      description: 201 Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GroupResponseObject'
  parameters:
    GroupId:
      name: groupId
      in: path
      description: A group's unique id can be identified using the Retrieve all Groups endpoint with a filter parameter
      schema:
        type: string
      required: true
    Count:
      name: count
      in: query
      description: Specifies the maximum number of resources to return in a single page of results.
      schema:
        type: integer
        format: int32
        default: 25
        minimum: 0
        maximum: 1000
    ExcludedAttributes:
      name: excludedAttributes
      in: query
      description: A comma-separated list of attributes to exclude from the resources in the response.
      schema:
        type: string
    XAsUserId:
      name: x-as-user-id
      in: header
      description: Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or `x-as-user-email` is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. More information about [permissions](https://support.ironcladapp.com/hc/en-us/articles/23063233934999-Ironclad-Permissions-Overview).
      required: false
      schema:
        type: string
        example: 5f0375c4cdc1927a3c5edcd3
    XAsUserEmail:
      name: x-as-user-email
      in: header
      description: Denotes the actor of the request. When used, the API will take into account this user's permissions and access. This or `x-as-user-id` is required when the associated token was produced from the Client Credentials grant or with legacy bearer tokens on select endpoints. More information about [permissions](https://support.ironcladapp.com/hc/en-us/articles/23063233934999-Ironclad-Permissions-Overview).
      required: false
      schema:
        type: string
        example: jane.doe@test.com
    StartIndex:
      name: startIndex
      in: query
      description: The starting index for retrieving this resource. Resources are indexed based on when they were first added to Ironclad.
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
  requestBodies:
    GroupCreateRequestBody:
      content:
        application/json:
          schema:
            type: object
            required:
            - schemas
            - displayName
            properties:
              schemas:
                type: array
                default:
                - urn:ietf:params:scim:schemas:core:2.0:Group
                items:
                  type: string
              displayName:
                type: string
                description: The name you want to give the group in Ironclad.
              members:
                type: array
                items:
                  properties:
                    value:
                      type: string
                      description: The unique id of the user. User Ids can be found by filtering the Retrieve all Users endpoint.
                  required:
                  - value
                  type: object
  schemas:
    GroupResponseObject:
      type: object
      required:
      - schemas
      - id
      properties:
        schemas:
          type: array
          items:
            type: string
            example: urn:ietf:params:scim:schemas:core:2.0:Group
        displayName:
          type: string
          description: The name of the group.
          example: Legal Ops Group
        id:
          type: string
          description: The group's identifier.
          example: 74906dd6-f2c6-4442-8875-57846f15b061
        externalId:
          type: string
          description: An optional identifier of the group sourced from the identity provider.
          example: '123'
        members:
          type: array
          description: The list of users who are members of this group.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - User
                description: The type of member for this group. This is usually 'User'.
                example: User
              value:
                type: string
                description: The user's identifier.
                example: 2bf1bb84-f7ed-4a11-8cbe-138814f9fc21
        meta:
          type: object
          description: Metadata for the group.
          properties:
            resourceType:
              type: string
              enum:
              - Group
              description: 'Type of the SCIM resource. In this case: ''Group''.'
              example: Group
            location:
              type: string
              format: https-url
              description: The URI of the Group resource being returned.
              example: https://na1.ironcladapp.com/scim/v2/Groups/67e4488c605caf0d8aa2e5c6
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
  samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python