Arch User Roles API

openapi: 3.2.0
info:
  title: Arch Client User Roles API
  version: 0.1.0
  description: '# Arch Client API Documentation


    ## Getting Started


    To get started, you need to request credentials from us at api-support@arch.co.'
servers:
- url: /
host: arch.co
tags:
- name: User Roles
paths:
  /client-api/v0/user-roles:
    get:
      operationId: get-list-user-roles
      summary: Get a paginated list of user roles
      parameters:
      - name: limit
        in: query
        description: The number of user roles to return
        schema:
          type: integer
          default: 25
          maximum: 1000
      - name: offset
        in: query
        description: The number of user roles to skip before collecting results
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: accountIds
        in: query
        description: Only include roles on one of the account ids provided. Applies only to roles where `objectType` is `account`.
        example: 1,2,3,4
        schema:
          type: array
          items:
            type: integer
      - name: investingEntityIds
        in: query
        description: Only include roles on one of the investing entity ids provided. Applies only to roles where `objectType` is `investingEntity`.
        example: 10,12,13,14
        schema:
          type: array
          items:
            type: integer
      - name: userIds
        in: query
        description: Only include roles on one of the user ids provided.
        example: 1,2,3,4
        schema:
          type: array
          items:
            type: integer
      - name: objectType
        in: query
        description: 'Which type of object to include. Allowed values: `account` or `investingEntity`.


          **This field defaults to `account` for backwards compatibility.** Callers that want

          investing-entity or holding roles must provide this parameter.

          '
        example: investingEntity
        schema:
          type: array
          items:
            type: string
            enum:
            - account
            - investingEntity
      - name: roleType
        in: query
        description: 'Filter results to only include roles matching the specified portal name.

          Spaces and special characters must be URL-encoded.


          Example values (as they appear in the database):

          - `Tax Only` (in URL: `?roleType=Tax%20Only`)

          - `Full Access` (in URL: `?roleType=Full%20Access`)

          '
        example: Tax%20Only
        schema:
          type: string
      security:
      - BearerAuth: []
      description: 'Returns a paginated list of **direct** user roles. Only shows roles

        explicitly granted on accounts, investing entities, or holdings.

        Access inherited via parent folders is not expanded into this list.


        Each returned role identifies its target via a single `objectRef` (an `AccountRef`,

        `InvestingEntityRef`, or `HoldingRef`) along with an `objectType` discriminator. The

        legacy `accountId` and `userUrl` fields are still populated where applicable but are

        deprecated; new integrations should read `objectRef` and `userRef` instead.'
      tags:
      - User Roles
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRoleList'
        '403':
          description: No permission to view access to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No permission to view access to some accounts
        '500':
          description: Internal server error.
    post:
      summary: Create new user roles
      security:
      - BearerAuth: []
      tags:
      - User Roles
      requestBody:
        required: true
        description: A list of new user roles to create.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RequestUserRole'
      responses:
        '200':
          description: Success
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '403':
          description: No permission to invite to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No permission to invite to some accounts
        '409':
          description: Some user roles already exist
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Some user roles already exist
        '500':
          description: Internal server error.
      operationId: postClientApiV0UserRoles
      x-operation-id-source: derived
    delete:
      summary: Remove user roles
      security:
      - BearerAuth: []
      tags:
      - User Roles
      requestBody:
        required: true
        description: A list of user roles to remove.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RequestUserRole'
      responses:
        '200':
          description: Success
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '403':
          description: No access to some accounts
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No access to some accounts
        '409':
          description: Some user roles don't exist yet
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Some user roles don't exist yet
        '500':
          description: Internal server error.
      operationId: deleteClientApiV0UserRoles
      x-operation-id-source: derived
components:
  schemas:
    ResponseUserRole:
      type: object
      required:
      - kind
      - objectRef
      - userRef
      - roleType
      properties:
        kind:
          type: string
          enum:
          - user-role
        objectRef:
          description: 'Reference to the object this role applies to. The concrete ref can be an `AccountRef`,

            an `InvestingEntityRef`, or a `HoldingRef`. The `kind` field on the ref can be used

            as a discriminator.

            '
          oneOf:
          - $ref: '#/components/schemas/AccountRef'
          - $ref: '#/components/schemas/InvestingEntityRef'
          - $ref: '#/components/schemas/HoldingRef'
          discriminator:
            propertyName: kind
            mapping:
              account-ref: '#/components/schemas/AccountRef'
              investing-entity-ref: '#/components/schemas/InvestingEntityRef'
              holding-ref: '#/components/schemas/HoldingRef'
        accountId:
          type: integer
          deprecated: true
          description: '**Deprecated.** Use `objectRef.id` instead. Only populated for

            account roles; omitted for investing-entity and holding roles.

            Retained for backwards compatibility.

            '
          example: 56
        userRef:
          $ref: '#/components/schemas/UserRef'
        userUrl:
          type: string
          deprecated: true
          description: '**Deprecated.** Use `userRef.url` instead. Retained for backwards compatibility.

            '
          example: /users/15
        roleType:
          type: string
          description: 'The role type. May include additional universal and custom role types beyond those

            available for POST and DELETE requests, depending on your Arch configuration.

            '
          example: Tax Only
    RoleType:
      type: string
      example: Tax Only
      enum:
      - Full Access
      - Tax Only
      - Restricted Tax Only
      - View Only
      - File Only
      - Informed Tax Only
      - View Only with Task Completion
      - Restricted Investor
      - Investment Team
      description: 'The type of role. Only the values listed below are accepted.

        '
    UserRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - user-ref
        id:
          type: integer
          description: The ID of the referenced user
          example: 15
        url:
          type: string
          description: A relative url to the referenced user
          example: /users/15
        name:
          type: string
          description: The display name of the referenced user
          example: John Smith
    InvestingEntityRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - investing-entity-ref
        id:
          type: number
          description: The ID of the referenced investing entity
          example: 711
        url:
          type: string
          description: A relative url to the referenced investing entity
          example: /investing-entities/711
        name:
          type: string
          description: The name of the referenced investing entity
          example: Investing Entity 711
    RequestUserRole:
      type: object
      required:
      - accountId
      - userId
      - roleType
      properties:
        accountId:
          type: integer
          example: 56
        userId:
          type: integer
          example: 15
        roleType:
          $ref: '#/components/schemas/RoleType'
          example: Tax Only
    AccountRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - account-ref
        id:
          type: number
          description: The ID of the referenced account
          example: 56
        url:
          type: string
          description: A relative url to the referenced account
          example: /account/56
        name:
          type: string
          description: The name of the referenced account
          example: Account 56
    HoldingRef:
      type: object
      required:
      - kind
      - id
      - url
      properties:
        kind:
          type: string
          enum:
          - holding-ref
        id:
          type: number
          description: The ID of the referenced holding
          example: 112
        url:
          type: string
          description: A relative url to the referenced holding
          example: /holdings/112
        name:
          type: string
          description: The name of the referenced holding
          example: Holding 112
    UserRoleList:
      type: object
      required:
      - kind
      - selfUrl
      - contents
      properties:
        kind:
          type: string
          description: page
        selfUrl:
          type: string
          description: The relative URL for accessing this resource via the Arch Client API
          example: /user-roles
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ResponseUserRole'
        prev:
          type: string
          description: The relative URL for the previous page of user roles
          example: null
        next:
          type: string
          description: The relative URL for the next page of user roles
          example: /user-roles?offset=25
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT