OutSystems Users API

openapi: 3.2.0
info:
  title: User and Access Management Users API
  description: REST endpoints for retrieving and managing user and access in your organization.
  version: v1
servers:
- url: https://ODC_PORTAL_DOMAIN/api/identity/v1
  description: Replace ODC_PORTAL_DOMAIN with the domain of your organization.
- url: https://{odc-portal-domain}/api/identity/v1
  description: User and Access Management API
  variables:
    odc-portal-domain:
      default: ODC_PORTAL_DOMAIN
      description: The domain of your organization
security:
- bearerAuth: []
tags:
- name: users
paths:
  /users/bulk:
    post:
      tags:
      - users
      summary: Bulk create users and optionally in the built-in identity provider.
      description: "The number of users added must be between 1 and 100 (inclusive), otherwise a bad request is returned.\nReturns an operations status object with an operation key that can be used later to get the status of the bulk create.\n            \nAPI Client needs the User management > Manage users permission.\n\nAPI Client needs the **User management > Manage users** permission."
      operationId: BulkUserProfile_CreateBulkUserProfilesOperation
      requestBody:
        description: Bulk Create User Request.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserProfileCreateApiRequestBulkApiRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserProfileCreateApiRequestBulkApiRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUserProfileOperationApiRecordBulkApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage users** permission.
  /users/bulk/{key}:
    get:
      tags:
      - users
      summary: Get the bulk user operation status.
      description: "Returns an operations status object that contains the overall status of the bulk operation.\nIf the bulk operation has a Finished or FinishedWithError status,\nthe result of each and every item in the list is returned as well.\nIf the bulk operation has a Pending or Processing status, only the overall status is returned.\n            \nAPI Client needs the User management > Manage users permission.\n\nAPI Client needs the **User management > Manage users** permission."
      operationId: BulkUserProfile_GetBulkUserProfileOperationStatus
      parameters:
      - name: key
        in: path
        description: Key of the operation that was obtained during submitting bulk operation.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUserProfileOperationApiRecordBulkApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage users** permission.
  /users/{key}/application-roles/{roleKey}:
    post:
      tags:
      - users
      summary: Grants an application role to a user.
      description: 'Assigns an application role to a user by providing the application role key and the user key.


        API Client needs the **User management > Manage end-user access** permission.'
      operationId: UserApplicationRoles_GrantApplicationRoleToUser
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: roleKey
        in: path
        description: Application role creation request.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage end-user access** permission.
    delete:
      tags:
      - users
      summary: Revokes an application role to a user.
      description: 'Revokes an application role from a user by providing the user key and application role key.


        API Client needs the **User management > Manage end-user access** permission.'
      operationId: UserApplicationRoles_RevokeApplicationRoleForUser
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: roleKey
        in: path
        description: Role key for the application.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage end-user access** permission.
  /users/{key}/application-roles:
    get:
      tags:
      - users
      summary: Returns the list of application roles associated with a user.
      description: 'Returns a list of application roles associated with a user that match the specified filters. Use query parameters to refine the search.


        API Client needs the **User management > View end users** permission.'
      operationId: UserApplicationRoles_QueryUserApplicationRoles
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: nameContains
        in: query
        description: Filters application roles by name.
        schema:
          type: string
      - name: assetKey
        in: query
        description: Only returns application roles for the specified asset. Mutually exclusive with `assetKeys`.
        schema:
          type: string
          format: uuid
      - name: assetKeys
        in: query
        description: Only returns application roles for any of the specified assets. Comma-separated list of asset keys. Mutually exclusive with `assetKey`.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: environmentKey
        in: query
        description: Only returns application roles in the specified environment (stage). Mutually exclusive with `environmentKeys`.
        schema:
          type: string
          format: uuid
      - name: environmentKeys
        in: query
        description: Only returns application roles in any of the specified environments (stages). Mutually exclusive with `environmentKey`.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: portfolioKeys
        in: query
        description: Only returns application roles in the environments belonging to any of the specified portfolios.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: groupKeys
        in: query
        description: Only returns application roles inherited from the specified groups.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: applicationRoleKeys
        in: query
        description: Only returns the application roles matching any of the specified keys. Comma-separated list of application role keys.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: sort
        in: query
        description: 'Used for sorting the list. Ascending by default. Prepend a hyphen, "-", to get a descending sort, for example "-name". Default: name. Allowed: name, environmentKey or assetKey.'
        schema:
          type: string
      - name: limit
        in: query
        description: 'Maximum number of results returned. Allowed values: 1 to 100 Default value: 100.'
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: 'Offset of the first result returned. Default value: 0.'
        schema:
          type: integer
          format: int32
      - name: assignmentSources
        in: query
        description: 'Filters by assignment source. Repeatable. Allowed: Direct, GroupAssigned, GroupMapped. Empty or omitted defaults to Direct. The IsDirectlyAssigned flag and AssignedGroups list on each returned role reflect only the selected sources.'
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AssignmentSource'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserApplicationRoleApiResponsePaginatedResponseApi'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > View end users** permission.
  /users/{key}/organization-roles:
    get:
      tags:
      - users
      summary: Returns the list of organization roles associated with a user.
      description: 'Returns the list of organization roles associated with a user.

        If the authenticated user is requesting their own roles, no permission is required.


        API Client needs the **User management > View members** or **User management > Manage users** permissions.'
      operationId: UserOrganizationRoles_GetUserOrganizationRoles
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: scopes
        in: query
        description: Optional. Comma-separated. `Organization` returns roles assigned in Organization scope; `Asset` returns roles assigned in Asset scope. Both together (or omitted) returns all.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationRoleAssignmentScope'
      - name: assetKeys
        in: query
        description: Optional. Comma-separated list of asset keys. Only returns organization roles assigned in Asset scope for any of the specified assets.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: limit
        in: query
        description: Maximum number of results returned. The value must be within 1 - 100 (both inclusive). The default value is 100.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Starting point or position of the first result returned. The default value is 0.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationRoleByUserApiResponsePaginatedResponseApi'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > View members** or **User management > Manage users** permissions.
  /users/{key}/organization-roles/{roleKey}:
    post:
      tags:
      - users
      summary: Grant organization roles to a user.
      description: 'Assigns organization roles to a user based on the user key.


        API Client needs the **User management > Manage member access** permission.'
      operationId: UserOrganizationRoles_GrantOrganizationRoleToUser
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: roleKey
        in: path
        description: Organization role key.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Contains role validity period and asset keys for which we assign this organization role.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/GrantDetailsRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/GrantDetailsRequest'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage member access** permission.
    delete:
      tags:
      - users
      summary: Delete a user's organization roles.
      description: 'Revokes organization roles for a user.


        API Client needs the **User management > Manage member access** permission.'
      operationId: UserOrganizationRoles_RevokeOrganizationRoleForUser
      parameters:
      - name: key
        in: path
        description: User key.
        required: true
        schema:
          type: string
          format: uuid
      - name: roleKey
        in: path
        description: Organization role key.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Revoke details contains the asset keys for which to revoke the organization role.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RevokeDetailsRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RevokeDetailsRequest'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage member access** permission.
  /users/count:
    get:
      tags:
      - users
      summary: Returns the user count based on specified conditions.
      description: 'Returns the user count that match the specified filters. Use query parameters to refine the search.


        API Client needs the **User management > View end users** or **User management > View members** or **User management > Manage users** permissions. If API Client has the **User management > View end users** permission, retrieves the list of users with end-user roles. If API Client has the **User management > View members** permission, retrieves the list of users with organization roles. To get a list of all users (with or without roles), the API client needs either both the **User management > View end users** and **User management > View members** permissions, or the **User management > Manage users** permission.'
      operationId: UserProfile_CountUsers
      parameters:
      - name: domains
        in: query
        description: Only counts users with the specified domains.
        schema:
          type: array
          items:
            type: string
      - name: status
        in: query
        description: Only counts users with the specified status.
        schema:
          allOf:
          - $ref: '#/components/schemas/UserProfileStatus'
      - name: hasOrganizationRoles
        in: query
        description: When set to true, only counts users that have at least one organization role. Default is false.
        schema:
          type: boolean
      - name: hasApplicationRoles
        in: query
        description: When set to true, only counts users that have at least one application role. Default is false.
        schema:
          type: boolean
      - name: environmentKeys
        in: query
        description: Only counts users that have roles in any of the specified environments (stages).
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: portfolioKeys
        in: query
        description: Only counts users that have roles in any of the specified portfolios.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: loggedInEnvironmentKeys
        in: query
        description: Only counts users that have logged in to any of the specified environments (stages). When combined with last login date filters, the date range applies to the per-environment login timestamp.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: loggedInPortfolioKeys
        in: query
        description: Only counts users that have logged in to any environment in the specified portfolios. When combined with last login date filters, the date range applies to the per-environment login timestamp.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: lastLoginAtSince
        in: query
        description: Only counts users whose last login occurred on or after the specified date and time. Applies to the top-level last login unless logged-in environment or portfolio filters are specified.
        schema:
          type: string
          format: date-time
      - name: lastLoginAtTo
        in: query
        description: Only counts users whose last login occurred before or on the specified date and time. Applies to the top-level last login unless logged-in environment or portfolio filters are specified.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileCountApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > View end users** or **User management > View members** or **User management > Manage users** permissions. If API Client has the **User management > View end users** permission, retrieves the list of users with end-user roles. If API Client has the **User management > View members** permission, retrieves the list of users with organization roles. To get a list of all users (with or without roles), the API client needs either both the **User management > View end users** and **User management > View members** permissions, or the **User management > Manage users** permission.
  /users:
    post:
      tags:
      - users
      summary: Creates a new user.
      description: 'Creates a new user by specifying the user information. You can provide the user''s name, photo URL, and active status. Additionally, the AddToBuiltInIdentityProvider can be used to add the user to the built-in provider.


        API Client needs the **User management > Manage users** permission.'
      operationId: UserProfile_CreateUser
      requestBody:
        description: The user object with the necessary information.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserProfileCreateApiRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UserProfileCreateApiRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileCreateResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-os-permissions: API Client needs the **User management > Manage users** permission.
    get:
      tags:
      - users
      summary: Returns the list of users based on specified conditions.
      description: 'Returns a list of users that match the specified filters. Use query parameters to refine the search.


        API Client needs the **User management > View end users** or **User management > View members** or **User management > Manage users** permissions. If API Client has the **User management > View end users** permission, retrieves the list of users with end-user roles. If API Client has the **User management > View members** permission, retrieves the list of users with organization roles. To get a list of all users (with or without roles), the API client needs either both the **User management > View end users** and **User management > View members** permissions, or the **User management > Manage users** permission.'
      operationId: UserProfile_QueryUsers
      parameters:
      - name: nameOrEmailContains
        in: query
        description: "Filters users by name or email address. Parameter value must be URL-encoded (percent-encoding) to ensure it's correctly interpreted by the server. Example: Searching for an email with a +\n            \n Incorrect: .../users?email=`john+doe@example.com`.\n            \n Correct: .../users?email=`john%2Bdoe@example.com`"
        schema:
          type: string
      - name: nameOrEmailOrUsernameContains
        in: query
        description: "Filters users by name or email address or username. Parameter value must be URL-encoded (percent-encoding) to ensure it's correctly interpreted by the server. Example: Searching for an email with a +\n            \n Incorrect: .../users?email=`john+doe@example.com`.\n            \n Correct: .../users?email=`john%2Bdoe@example.com`"
        schema:
          type: string
      - name: userKeys
        in: query
        description: Only returns users that match the specified keys. For more than one key, separates the keys with a comma. Allows up to 20 user keys.
        schema:
          type: string
      - name: assetKey
        in: query
        description: Only returns users that have roles for the specified Asset.
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        description: Only returns users with the specified status.
        schema:
          allOf:
          - $ref: '#/components/schemas/UserProfileStatus'
      - name: lastLoginAtSince
        in: query
        description: Only returns users whose last login occurred on or after the specified date and time.
        schema:
          type: string
          format: date-time
      - name: lastLoginAtTo
        in: query
        description: Only returns users whose last login occurred before or on the specified date and time.
        schema:
          type: string
          format: date-time
      - name: hasOrganizationRoles
        in: query
        description: When set to true, only returns users that have at least one organization role. Default is false.
        schema:
          type: boolean
      - name: hasApplicationRoles
        in: query
        description: When set to true, only returns users that have at least one application role. Default is false.
        schema:
          type: boolean
      - name: sort
        in: query
        description: 'Used for sorting the list. Ascending by default. Prepend a hyphen, "-", to get a descending sort, for example "-name". Default: name. Allowed: key, name, email, status, lastLoginAt.'
        schema:
          type: string
      - name: environmentKey
        in: query
        description: Only returns users that have roles in the specified environment (stage). Mutually exclusive with `environmentKeys`.
        schema:
          type: string
          format: uuid
      - name: environmentKeys
        in: query
        description: Only returns users that have roles in any of the specified environments (stages). Comma-separated list of environment keys. Mutually exclusive with `environmentKey`.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: portfolioKeys
        in: query
        description: Only returns users that have roles in any of the specified portfolios.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: domains
        in: query
        description: Only returns users with the specified domains.
        schema:
          type: array
          items:
            type: string
      - name: loggedInEnvironmentKeys
        in: query
        description: Only returns users that have logged in to any of the specified environments (stages). When combined with last login date filters, the date range applies to the per-environment login timestamp.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: loggedInPortfolioKeys
        in: query
        description: Only returns users that have logged in t

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/outsystems/refs/heads/main/openapi/outsystems-users-api-openapi.yml