Authenticx (Scim) Users API

openapi: 3.2.0
info:
  title: AcxApi Production (Scim) Users API
  version: v1
servers:
- url: https://api.beauthenticx.com
  description: AcxApi Production Server
security:
- {}
tags:
- name: (Scim) Users
paths:
  /scim/v2/Users:
    get:
      tags:
      - (Scim) Users
      summary: Get Users
      description: 'Returns the list of all users in scim user schema format.

        Supports, filtering, sorting, pagination, and attribute picking

        as defined in rfc 7644.'
      parameters:
      - name: filter
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2'
        schema:
          type: string
      - name: sortBy
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.3'
        schema:
          type: string
      - name: sortOrder
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.3'
        schema:
          type: string
      - name: startIndex
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4'
        schema:
          type: integer
          format: int32
      - name: count
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4'
        schema:
          type: integer
          format: int32
      - name: attributes
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5'
        schema:
          type: string
      - name: excludedAttributes
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5'
        schema:
          type: string
      responses:
        '200':
          description: Returns the filtered, sorted, and/or paginated users.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ListResponse_Of_User'
        '400':
          description: Bad Request
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
      operationId: getScimV2Users
      x-operation-id-source: derived
    post:
      tags:
      - (Scim) Users
      summary: Create User
      description: Creates a user with the provided information.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.User.CreateUserRequest'
          application/scim+json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.User.CreateUserRequest'
      responses:
        '201':
          description: Returns the created user
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Resources.User'
        '400':
          description: An invalid scim schema was provided or no email was provided
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
        '409':
          description: One or more required fields belonged to an existing user
          content:
            application/scim+json:
              schema:
                type: string
      operationId: postScimV2Users
      x-operation-id-source: derived
  /scim/v2/Users/{UserId}:
    delete:
      tags:
      - (Scim) Users
      summary: Delete User
      description: 'This action does not delete the user record from the

        database, it marks the `disabled` field as `true`.

        Therefore, any attempts to create a user with the same user

        name as an existing, deleted user, will fail.'
      parameters:
      - name: UserId
        in: path
        description: The id of the user to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The user was successfully deleted
          content:
            application/scim+json:
              schema:
                type: string
        '400':
          description: An invalid user id was provided or the user did not exist
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
      operationId: deleteScimV2UsersByUserId
      x-operation-id-source: derived
    get:
      tags:
      - (Scim) Users
      summary: Get User
      description: Gets a specific user by their id.
      parameters:
      - name: UserId
        in: path
        description: The id of the user to retrieve
        required: true
        schema:
          type: string
      - name: attributes
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5'
        schema:
          type: string
      - name: excludedAttributes
        in: query
        description: 'See: https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5'
        schema:
          type: string
      responses:
        '200':
          description: Returns the user with the specified id
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Resources.User'
        '400':
          description: Bad Request
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
        '404':
          description: A user with the specified id was not found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
      operationId: getScimV2UsersByUserId
      x-operation-id-source: derived
    patch:
      tags:
      - (Scim) Users
      summary: Patch User
      parameters:
      - name: UserId
        in: path
        description: The id of the user you wish to patch
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.Patch.PatchRequest'
          application/scim+json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.Patch.PatchRequest'
      responses:
        '200':
          description: The updated user
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Resources.User'
        '400':
          description: An invalid user id was provided or one of the patch operations was faulty
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
      operationId: patchScimV2UsersByUserId
      x-operation-id-source: derived
    put:
      tags:
      - (Scim) Users
      summary: Update User
      description: 'Updates a user with specified id with the provided

        information.'
      parameters:
      - name: UserId
        in: path
        description: The id of the user to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.User.UpdateUserRequest'
          application/scim+json:
            schema:
              $ref: '#/components/schemas/AcxApi.Scim.Models.User.UpdateUserRequest'
      responses:
        '200':
          description: Returns the updated user
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Resources.User'
        '400':
          description: An invalid user id or scim schema was provided or the user did not exist
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/AcxApi.Scim.Models.ErrorResponse'
      operationId: putScimV2UsersByUserId
      x-operation-id-source: derived
components:
  schemas:
    System.Text.Json.Nodes.JsonNode:
      type: object
      properties:
        options:
          $ref: '#/components/schemas/System.Text.Json.Nodes.JsonNodeOptions'
        parent:
          $ref: '#/components/schemas/System.Text.Json.Nodes.JsonNode'
        root:
          $ref: '#/components/schemas/System.Text.Json.Nodes.JsonNode'
      additionalProperties: false
    AcxApi.Scim.Models.User.UpdateUserRequest:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
        userName:
          type:
          - string
          - 'null'
          description: The users user name
          example: john.doe@organization.com
        externalId:
          type:
          - string
          - 'null'
          description: 'External identity provider identifier. Stored as the SAML provider

            user code on the Authenticx user.'
        name:
          $ref: '#/components/schemas/AcxApi.Scim.Models.Name'
        emails:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users emails
        phoneNumbers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users phone numbers, if any
        timezone:
          type:
          - string
          - 'null'
          description: The users time zone, in IANA form.
          example: America/Indiana/Indianapolis
        active:
          type:
          - boolean
          - 'null'
          description: Whether the user is active or not.
          example: true
        enableAgentUser:
          type:
          - boolean
          - 'null'
          description: Set to true to simultaneously create a matching, linked agent-user.
          example: true
        urn:authenticx:params:scim:schemas:extension:agent:2.0:User:
          $ref: '#/components/schemas/AcxApi.Scim.Models.User.AgentUserExtension'
        roles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Role'
          description: The Authenticx role to assign to the user.
      additionalProperties: false
    System.Text.Json.Nodes.JsonNodeOptions:
      type: object
      properties:
        propertyNameCaseInsensitive:
          type: boolean
      additionalProperties: false
    AcxApi.Scim.Models.Role:
      type: object
      properties:
        value:
          type:
          - string
          - 'null'
          description: 'The name of the Authenticx role to assign. Role names are matched

            case insensitively within the calling organization. An Authenticx

            role id may also be supplied.'
          example: Analyst
        display:
          type:
          - string
          - 'null'
          description: 'Human readable name of the role. Populated by the server on read

            and ignored on write.'
          example: Analyst
        primary:
          type: boolean
          description: 'Indicates which role should be applied when more than one is

            supplied. Authenticx users hold a single role, so exactly one

            entry must be marked primary when multiple roles are provided.'
          example: true
        type:
          type:
          - string
          - 'null'
          description: 'Optional label describing the kind of role. Not interpreted by

            Authenticx.'
      additionalProperties: false
      description: 'A single entry of the scim "roles" multi valued attribute.

        <a href="https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2">Scim documentation on roles</a>'
    AcxApi.Scim.Models.ErrorResponse:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of schemas for this error response.
        scimType:
          type:
          - string
          - 'null'
          description: The type of error this was, as defined by scim
          example: invalidSyntax
        detail:
          type:
          - string
          - 'null'
          description: A detailed error message explaining what went wrong
        status:
          type:
          - string
          - 'null'
          description: The status code of the response
          example: '400'
      additionalProperties: false
    ListResponse_Of_User:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Always contains "urn:ietf:params:scim:api:messages:2.0:ListResponse".

            Declared as a property rather than a field so that it is serialized;

            System.Text.Json ignores fields by default.'
        itemsPerPage:
          type:
          - integer
          - 'null'
          description: The number of items returned per page
          format: int32
          example: 10
        startIndex:
          type:
          - integer
          - 'null'
          description: The 1-based index of the first result in the current page.
          format: int32
          example: 1
        totalResults:
          type: integer
          description: 'The total number of resources matching the request, which for a

            paginated request is larger than the number of resources returned.

            Falls back to the size of this page when the caller has not set it.

            <a href="https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2">Scim documentation on list responses</a>'
          format: int32
          example: 10
        Resources:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Resources.User'
          description: The resources returned by this response
          readOnly: true
      additionalProperties: false
    AcxApi.Scim.Models.User.CreateUserRequest:
      required:
      - emails
      - name
      - userName
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
        userName:
          minLength: 1
          type: string
          description: The users user name
          example: john.doe@organization.com
        externalId:
          type:
          - string
          - 'null'
          description: 'External identity provider identifier. Stored as the SAML provider

            user code on the Authenticx user.'
        name:
          $ref: '#/components/schemas/AcxApi.Scim.Models.Name'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users emails
        phoneNumbers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users phone numbers, if any
        timezone:
          type:
          - string
          - 'null'
          description: The users time zone, in IANA form.
          example: America/Indiana/Indianapolis
        active:
          type:
          - boolean
          - 'null'
          description: Whether the user is active or not.
          example: true
        enableAgentUser:
          type:
          - boolean
          - 'null'
          description: Set to true to simultaneously create a matching, linked agent-user.
          example: true
        urn:authenticx:params:scim:schemas:extension:agent:2.0:User:
          $ref: '#/components/schemas/AcxApi.Scim.Models.User.AgentUserExtension'
        roles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Role'
          description: The Authenticx role to assign to the user.
      additionalProperties: false
    AcxApi.Scim.Models.Patch.PatchOperation:
      type: object
      properties:
        op:
          type:
          - string
          - 'null'
          description: 'The operation to perform. Normalized to lower case on the way in:

            scim defines the operation names in lower case but identity

            providers are inconsistent about it, Entra in particular sending

            "Add"/"Replace"/"Remove". Normalizing once here keeps validation and

            dispatch from ever disagreeing about casing.'
        path:
          type:
          - string
          - 'null'
        value:
          $ref: '#/components/schemas/System.Text.Json.Nodes.JsonNode'
        isValidOp:
          type: boolean
          readOnly: true
        isPathRequired:
          type: boolean
          readOnly: true
        isValueRequired:
          type: boolean
          readOnly: true
      additionalProperties: false
    AcxApi.Scim.Models.User.AgentUserExtension:
      type: object
      properties:
        enableAgentUser:
          type:
          - boolean
          - 'null'
        agentId:
          type:
          - string
          - 'null'
          format: uuid
      additionalProperties: false
      description: 'Authenticx-specific SCIM user extension for provisioning the linked

        agent record that has no standard SCIM equivalent.'
    AcxApi.Scim.Models.Metadata:
      type: object
      properties:
        resourceType:
          type:
          - string
          - 'null'
        created:
          type:
          - string
          - 'null'
          description: 'Null when the underlying record predates this api tracking it - a

            legacy row this api never wrote. Left genuinely absent rather than

            reporting a fabricated "now": a fake value would satisfy every

            "meta.lastModified gt X" filter forever, permanently mis-flagging

            an untouched account as just-changed on every incremental sync.'
          format: date-time
        lastModified:
          type:
          - string
          - 'null'
          format: date-time
        version:
          type:
          - string
          - 'null'
          description: "If ETags are enabled in the service provider config, weak\nETags are used to version resources. The ETag header attribute\nshould also be set when ETags are enabled.\n            \n<a href=\"https://datatracker.ietf.org/doc/html/rfc7644#section-3.14\">Scim documentation on versioning</a>"
        location:
          type:
          - string
          - 'null'
          description: "Used to provide information about where the resource\nis located on the server.\nex.\n    - https://localhost:5001/scim/v2/Users/user-id-here"
      additionalProperties: false
    AcxApi.Scim.Models.Contact:
      type: object
      properties:
        primary:
          type: boolean
        value:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
      additionalProperties: false
    AcxApi.Scim.Models.Patch.PatchRequest:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
        operations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Patch.PatchOperation'
        enableAgentUser:
          type:
          - boolean
          - 'null'
        urn:authenticx:params:scim:schemas:extension:agent:2.0:User:
          $ref: '#/components/schemas/AcxApi.Scim.Models.User.AgentUserExtension'
      additionalProperties: false
    AcxApi.Scim.Resources.User:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            type: string
        meta:
          $ref: '#/components/schemas/AcxApi.Scim.Models.Metadata'
        id:
          type:
          - string
          - 'null'
          description: Id of the user assigned by the service provider
          example: c4be4102-23ea-4780-a9a7-444c810daee4
        externalId:
          type:
          - string
          - 'null'
          description: Maps to the SAML provider user code stored on the application user.
        userName:
          type:
          - string
          - 'null'
          description: The users user name
          example: john.doe@organization.com
        name:
          $ref: '#/components/schemas/AcxApi.Scim.Models.Name'
        displayName:
          type:
          - string
          - 'null'
          description: 'The name intended for display. Both Entra and Okta map this

            attribute by default.'
          example: John Doe
        timezone:
          type:
          - string
          - 'null'
          description: The users time zone, in IANA form.
          example: America/Indiana/Indianapolis
        emails:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users emails
        phoneNumbers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Contact'
          description: A list of the users phone numbers, if any
        active:
          type: boolean
          description: Whether the user is active or not.
          example: true
        agentId:
          type:
          - string
          - 'null'
          description: The unique agent ID associated with this user, if any.
          format: uuid
        urn:authenticx:params:scim:schemas:extension:agent:2.0:User:
          $ref: '#/components/schemas/AcxApi.Scim.Models.User.AgentUserExtension'
        roles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AcxApi.Scim.Models.Role'
          description: 'The Authenticx role assigned to the user. An Authenticx user holds

            a single role, so this contains at most one entry on read.'
      additionalProperties: false
    AcxApi.Scim.Models.Name:
      type: object
      properties:
        givenName:
          type:
          - string
          - 'null'
          description: The given or first name of the user
          example: John
        familyName:
          type:
          - string
          - 'null'
          description: The family or last name of the user
          example: Doe
      additionalProperties: false
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.beauthenticx.com/connect/token
          scopes:
            acxapi: Access to Acx API
x-provenance:
  method: harvested
  publisher: Authenticx
  source: https://api.beauthenticx.com/swagger/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)