openapi: 3.1.0
info:
  title: Ironclad OAuth 2.0 Authorization Users 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: Users
  description: Documentation on SCIM Users.
paths:
  /Users:
    get:
      summary: List all Users
      description: "Documentation on listing Users via SCIM. \n\n**OAuth Scope required:** `scim.users.readUsers`"
      operationId: retrieve-all-users
      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 users. 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: userName eq "alex.doe@example.com"
        schema:
          type: string
      - $ref: '#/components/parameters/ExcludedAttributes'
      responses:
        '200':
          $ref: '#/components/responses/UsersResponse200'
        '400':
          $ref: '#/components/responses/UserFilterResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
    post:
      summary: Create a User
      description: "Documentation on creating a User via SCIM. \n\n**OAuth Scope required:** `scim.users.createUsers`"
      operationId: create-a-user
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        $ref: '#/components/requestBodies/UserCreateRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/UserResponse201'
        '400':
          $ref: '#/components/responses/UserResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '409':
          $ref: '#/components/responses/AlreadyExistsResponse409'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
  /Users/{userId}:
    get:
      summary: Retrieve a User
      description: "Documentation on accessing User info via SCIM. \n\n**OAuth Scope required:** `scim.users.readUsers`"
      operationId: retrieve-a-user
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      responses:
        '200':
          $ref: '#/components/responses/UserResponse200'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
    patch:
      summary: Update User Data
      description: "Documentation on updating a User via SCIM. \n\n**OAuth Scope required:** `scim.users.updateUsers`"
      operationId: update-user-data
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - schemas
              properties:
                schemas:
                  type: array
                  default:
                  - urn:ietf:params:scim:api:messages:2.0:PatchOp
                  items:
                    type: string
                Operations:
                  type: array
                  items:
                    properties:
                      op:
                        type: string
                        description: Must be "add", "remove", or "replace"
                      path:
                        type: string
                        description: The path of the attribute that you wish to change (e.g., emails, name.givenName, name.familyName)
                      value:
                        type: string
                        description: The value you wish to use for "add" or "replace" operations. The "remove" operation does not take the "value" parameter.
                    required:
                    - op
                    - path
                    type: object
      responses:
        '200':
          $ref: '#/components/responses/UserResponse200'
        '400':
          $ref: '#/components/responses/UserResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
    put:
      summary: Replace a User
      description: "Documentation on replacing a User via SCIM. \n\n**OAuth Scope required:** `scim.users.updateUsers`"
      operationId: replace-a-user
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/ExcludedAttributes'
      requestBody:
        $ref: '#/components/requestBodies/UserCreateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/UserResponse200'
        '400':
          $ref: '#/components/responses/UserResponse400'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
    delete:
      summary: Delete a User
      description: "Delete a user on Ironclad. If the deletion is successful, all active workflows associated with the deleted user should be automatically reassigned to the default user within the admin group. To learn how to set a default user, see the [Manage Groups](https://support.ironcladapp.com/hc/en-us/articles/12286570480791-Manage-Groups) guide. \n\n**OAuth Scope required:** `scim.users.deleteUsers`"
      operationId: delete-a-user
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          $ref: '#/components/responses/UserResponse204'
        '403':
          $ref: '#/components/responses/ForbiddenResponse403'
        '404':
          $ref: '#/components/responses/NotFoundResponse404'
        '500':
          $ref: '#/components/responses/ServerErrorResponse500'
      tags:
      - Users
components:
  responses:
    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'
    UserResponse204:
      description: 204 No Content
    UserFilterResponse400:
      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: name,lastName'
    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'
    UserResponse200:
      description: 200 OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserResponseObject'
    UserResponse201:
      description: 201 Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserResponseObject'
    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
    UsersResponse200:
      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 users that match this filter. This may be larger than the number of users 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/UserResponseObject'
              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
    UserResponse400:
      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 name.givenName: 123'
  schemas:
    UserResponseObject:
      type: object
      required:
      - schemas
      - id
      properties:
        schemas:
          type: array
          items:
            type: string
            example: urn:ietf:params:scim:schemas:core:2.0:User
        userName:
          type: string
          description: The email address of the user (e.g., jdoe@acme.com).
          example: alex.doe@example.com
        name:
          type: object
          description: The first name and last name of the user.
          properties:
            givenName:
              type: string
              description: The first name of the user.
              example: Alex
            familyName:
              type: string
              description: The last name of the user.
              example: Doe
        title:
          type: string
          description: The user's legal title.
          example: Vice President
        id:
          type: string
          description: The user's unique identifier.
          example: 6660d37dec0eac3deffb680e
        emails:
          type: array
          description: A list of emails associated with the user. The email with type work and primary flag is typically copied from the main email stored in the userName property.
          items:
            type: object
            properties:
              value:
                type: string
                description: The email address value.
                example: alex.doe@example.com
              type:
                type: string
                description: The type of email this is. Canonical values include 'work', 'home', and 'other'.
                example: work
              primary:
                type: boolean
                description: Whether this is the user's primary email address.
                example: true
                default: true
        active:
          type: boolean
          description: Whether this user is currently active. Ironclad users do not have the concept of active vs. inactive, and a SCIM User with active set to `false` will be removed from the company. On subsequent reads, inactive users would be not found.
          example: true
          default: true
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          type: object
          description: Enterprise User attributes
          properties:
            department:
              type: string
              description: Which department the user is a part of.
              example: Legal
        urn:ietf:params:scim:schemas:extension:ironclad:2.0:User:
          type: object
          description: Ironclad User attributes
          properties:
            departmentHead:
              type: string
              format: email
              description: The email address (username) of the user's department head.
              example: jane.doe@test.com
            provider:
              type: string
              enum:
              - local
              - magicLink
              - saml
              - google
              description: The user's authentication method.
              example: local
            allowProviderConversion:
              type: boolean
              description: Whether the user is allowed to convert from `local` to `google` provider.
              example: false
        meta:
          type: object
          description: Metadata for the user.
          properties:
            resourceType:
              type: string
              enum:
              - User
              description: 'Type of the SCIM resource. In this case: ''User''.'
              example: User
            created:
              type: string
              description: When the User was created.
              example: '2025-03-26T18:33:48.336Z'
            lastModified:
              type: string
              description: When the User was last modified.
              example: '2025-03-26T18:33:48.336Z'
            location:
              type: string
              format: url
              description: The URI of the User resource being returned.
              example: https://na1.ironcladapp.com/scim/v2/Users/67e4488c605caf0d8aa2e5c6
  requestBodies:
    UserCreateRequestBody:
      content:
        application/json:
          schema:
            type: object
            required:
            - schemas
            - userName
            - name
            properties:
              schemas:
                type: array
                default:
                - urn:ietf:params:scim:schemas:core:2.0:User
                items:
                  type: string
              userName:
                type: string
                description: The email address of the user (e.g., jdoe@acme.com).
              name:
                type: object
                description: The first name and last name of the user.
                properties:
                  givenName:
                    type: string
                    description: The first name of the user.
                  familyName:
                    type: string
                    description: The last name of the user.
              title:
                type: string
                description: The user's legal title.
              password:
                type: string
                description: "The user's password for username/password type sign in method. Required if there are no SAML configurations set up for the company. \n\nPassword requirements:\n- 16+ characters \n- At least one lowercase letter \n- At least one uppercase letter \n- At least one number \n- At least one special character (!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~)"
              active:
                type: boolean
                description: Whether the user is currently active. Ironclad users cannot be marked as inactive, and will be removed from the company if this is set to false.
                default: true
              urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
                type: object
                description: Enterprise User attributes
                properties:
                  department:
                    type: string
                    description: Which department the user is a part of.
                    example: Legal
              urn:ietf:params:scim:schemas:extension:ironclad:2.0:User:
                type: object
                description: Ironclad User attributes
                properties:
                  departmentHead:
                    type: string
                    format: email
                    description: The email address (username) of the user's department head.
                    example: jane.doe@test.com
                  allowProviderConversion:
                    type: boolean
                    description: Allow the user to convert from 'local' to 'google' provider.
                    example: false
  parameters:
    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
    UserId:
      name: userId
      in: path
      description: A user's unique id can be identified using the Retrieve all Users endpoint with a filter parameter
      schema:
        type: string
      required: true
    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
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
  samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python