openapi: 3.0.3
info:
  title: User Management API
  description: |
    This API lets you perform CRUD operations on users that exist in Auth0.
    In order to use the API, you need a PCS access token with either the
    permission **VIEW_USERS_AND_GROUPS** or **MODIFY_USERS_AND_GROUPS**. For example, if you want to delete a user belonging
    the **acme** tenant, you need a PCS token with **MODIFY_USERS_AND_GROUPS** issued by
    [central-manager.acme.pcm.pricer-plaza.com](https://central-manager.acme.pcm.pricer-plaza.com).
  version: 1.0.1
security:
  - bearer: [ ]

paths:
  /api/v1/users:
    get:
      operationId: ListUsersV0
      tags:
        - User
      parameters:
        - name: filter[tenant]
          in: query
          example: stage
          description: List the users belonging to this tenant
          required: true
          schema:
            type: string
        - name: page[size]
          in: query
          example: 10
          description: Max number of users for each page
          required: false
          schema:
            type: integer
        - name: sort
          in: query
          example: id
          description: Attribute by which users to be sorted. Use "-" prefix for DESC order
          schema:
            type: string
            enum:
              - id
              - -id
              - username
              - -username
              - email
              - -email
              - firstName
              - -firstName
              - lastName
              - -lastName
              - createdAt
              - -createdAt
          required: false
        - name: page[number]
          in: query
          example: 0
          required: false
          description: Index of users list page to be retrived
          schema:
            type: integer
      description: List all users the that you have permission to see.
      responses:
        200:
          description: |
            The request was successfully completed. The response is all the users that you are allowed to see.
            The list may be empty.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
    post:
      operationId: CreateUserV0
      tags:
        - User
      description: Create a new user. The password of the user will be automatically generated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreateRequest"
      responses:
        201:
          description: The user was successfully created. The response is the newly created user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
  /api/v1/users/{userId}:
    get:
      operationId: GetUserV0
      tags:
        - User
      parameters:
        - $ref: "#/components/parameters/UserId"
      description: Retrieve the user with the given id.
      responses:
        200:
          description: The user was successfully found and retrieved. The response is the found user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
    put:
      operationId: UpdateUserV0
      description: Update the user with the given id.
      tags:
        - User
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        200:
          description: The user was successfully updated. The response is the updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        207:
          description: The user was partially updated. The response is the updated user with errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
    delete:
      operationId: DeleteUserV0
      description: Delete the user with the given id.
      tags:
        - User
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        204:
          description: The user was successfully deleted.

  /api/v1/users/{userId}/change-password:
    patch:
      deprecated: true
      operationId: ChangePasswordV0
      description: Update the user passowrd with the given id.
      tags:
        - User
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
      responses:
        200:
          description: The user was successfully updated. The response is the updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
  /api/v2/users/{userId}/change-password:
    patch:
      operationId: ChangePasswordV2
      description: Update the user passowrd with the given id.
      tags:
        - User
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequestV2'
      responses:
        200:
          description: The user was successfully updated. The response is the updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
components:
  parameters:
    UserId:
      name: userId
      description: The id of the user. Should start with `auth0|`.
      in: path
      required: true
      schema:
        type: string
        example: auth0|aDYluEaK
  schemas:
    UserListResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            first:
              type: object
              items:
                $ref: "#/components/schemas/Links"
            last:
              type: object
              items:
                $ref: "#/components/schemas/Links"
            next:
              type: object
              items:
                $ref: "#/components/schemas/Links"
            prev:
              type: object
              items:
                $ref: "#/components/schemas/Links"
        data:
          type: array
          items:
            $ref: "#/components/schemas/UserResponse"

    Links:
      type: object
      required:
        - href
      properties:
        href:
          type: string
          description: Http url to reterive users based on query params
        meta:
          type: object
          description: Metadata to perform futher actions

    UserResponse:
      type: object
      required:
        - id
        - email
        - serviceUser
        - tenantName
        - createdAt
        - updatedAt
        - username
        - firstName
        - lastName
        - lastLogin
      properties:
        id:
          type: string
          description: The Auth0 id for this user
          example: auth0|aDYluEaK
        email:
          type: string
          format: email
          description: The email of the user, has to be unique
        serviceUser:
          type: boolean
          description: True if the user is a service user, false otherwise
        tenantName:
          type: string
          description: The name of the tenant this user belongs to
          example: acme
        createdAt:
          type: string
          format: date-time
          description: The UTC date time when the user was created
        updatedAt:
          type: string
          format: date-time
          description: The UTC date time when the user was last updated
          nullable: true
        username:
          type: string
          description: The username of the user
          example: jmax
        firstName:
          type: string
          description: The first name of the user
          example: James
        lastName:
          type: string
          description: The last name of the user
          example: Maxwell
        lastLogin:
          type: string
          format: date-time
          description: The UTC date time when the user last logged in
          nullable: true

    UserCreateRequest:
      required:
        - email
        - serviceUser
        - tenantName
        - username
        - firstName
        - lastName
      properties:
        email:
          $ref: "#/components/schemas/UserResponse/properties/email"
        serviceUser:
          $ref: "#/components/schemas/UserResponse/properties/serviceUser"
        tenantName:
          $ref: "#/components/schemas/UserResponse/properties/tenantName"
        username:
          $ref: "#/components/schemas/UserResponse/properties/username"
        password:
          type: string
          description: (Optional) The passowrd for the user. If not provided, API would set an random password
        firstName:
          $ref: "#/components/schemas/UserResponse/properties/firstName"
        lastName:
          $ref: "#/components/schemas/UserResponse/properties/lastName"

    UserUpdateRequest:
      required:
        - email
        - firstName
        - lastName
      properties:
        email:
          $ref: "#/components/schemas/UserResponse/properties/email"
        firstName:
          $ref: "#/components/schemas/UserResponse/properties/firstName"
        lastName:
          $ref: "#/components/schemas/UserResponse/properties/lastName"

    ChangePasswordRequest:
      required:
        - newPassword
      properties:
        newPassword:
          type: string
          description: The username of the user
          example: strong-password

    ChangePasswordRequestV2:
      required:
        - newPassword
        - currentPassword
      properties:
        currentPassword:
          type: string
          description: Current password of the user
          example: strong-password
        newPassword:
          type: string
          description: New password of the user
          example: strong-password

    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"

    Error:
      type: object
      properties:
        code:
          type: string
          description: A code which can be used when parsing the data. Not really human-friendly.
        detail:
          type: string
          description: A more descriptive message of the error.
        meta:
          type: object
          description: A key/value-map of additional data
          nullable: true
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT