Sonatype Nexus Repository Security management: users API

openapi: 3.2.0
info:
  title: 'Nexus Repository Manager REST Security management: users API'
  version: 3.97.2-02
servers:
- url: /service/rest
tags:
- name: 'Security management: users'
paths:
  /v1/security/users/{userId}:
    put:
      tags:
      - 'Security management: users'
      summary: Update an existing user
      operationId: updateSecurityUsers
      parameters:
      - name: userId
        in: path
        description: The userid the request should apply to.
        required: true
        schema:
          type: string
      requestBody:
        description: A representation of the user to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUser'
        required: true
      responses:
        '400':
          description: Password was not supplied in the body of the request
        '403':
          description: The user does not have permission to perform the operation.
        '404':
          description: User or user source not found in the system.
        '204':
          description: Success
    delete:
      tags:
      - 'Security management: users'
      summary: Delete a user
      operationId: deleteSecurityUsers
      parameters:
      - name: userId
        in: path
        description: The userid the request should apply to.
        required: true
        schema:
          type: string
      - name: realm
        in: query
        description: The realm the request should apply to.
        schema:
          type: string
      responses:
        '400':
          description: There was problem deleting a user. Consult the response body for more details
        '403':
          description: The user does not have permission to perform the operation.
        '404':
          description: User or user source not found in the system.
  /v1/security/users:
    get:
      tags:
      - 'Security management: users'
      summary: Retrieve a list of users.
      operationId: listSecurityUsers
      parameters:
      - name: userId
        in: query
        description: An optional term to search userids for.
        schema:
          type: string
      - name: source
        in: query
        description: An optional user source to restrict the search to.
        schema:
          type: string
      responses:
        '200':
          description: Users returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiUser'
        '400':
          description: Password was not supplied in the body of the request
        '403':
          description: The user does not have permission to perform the operation.
    post:
      tags:
      - 'Security management: users'
      summary: Create a new user in the default source
      operationId: createSecurityUsers
      requestBody:
        description: A representation of the user to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateUser'
        required: true
      responses:
        '200':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUser'
        '400':
          description: Invalid user data supplied
        '403':
          description: The user does not have permission to perform the operation.
  /v1/security/users/{userId}/change-password:
    put:
      tags:
      - 'Security management: users'
      summary: Change a user's password
      operationId: updateSecurityUsersChangePassword
      parameters:
      - name: userId
        in: path
        description: The userid the request should apply to.
        required: true
        schema:
          type: string
      requestBody:
        description: The new password to use.
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        '400':
          description: Password was not supplied in the body of the request
        '403':
          description: The user does not have permission to perform the operation.
        '404':
          description: User not found in the system.
        '204':
          description: Success
  /v1/security/users/{userId}/{realm}/user-token:
    get:
      tags:
      - 'Security management: users'
      summary: Get user token metadata for the given user
      description: Retrieves metadata for an existing user token. Both userId and realm are required parameters. The passCode is never returned in this response.
      operationId: getSecurityUsersUserToken
      parameters:
      - name: userId
        in: path
        description: The userId of the user to get the token for
        required: true
        schema:
          type: string
      - name: realm
        in: path
        description: The realm of the user to get the token for
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User token metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenXO'
        '400':
          description: User tokens are not enabled
        '403':
          description: Insufficient permissions to view user token
        '404':
          description: User not found in realm or token not found
        '422':
          description: Invalid realm
        '500':
          description: Unexpected server error
    post:
      tags:
      - 'Security management: users'
      summary: Create a user token for the given user
      description: Creates a new user token for the specified user. Both userId and realm are required parameters.
      operationId: createSecurityUsersUserToken
      parameters:
      - name: userId
        in: path
        description: The userId of the user to create the token for
        required: true
        schema:
          type: string
      - name: realm
        in: path
        description: The realm of the user to create the token for
        required: true
        schema:
          type: string
      responses:
        '201':
          description: User token successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenXO'
        '400':
          description: User tokens are not enabled
        '403':
          description: Insufficient permissions to create user token
        '404':
          description: User not found in realm
        '409':
          description: User token already exists for this user and realm
        '422':
          description: Invalid realm
        '500':
          description: Unexpected server error
    delete:
      tags:
      - 'Security management: users'
      summary: Delete the user token for the given user
      description: Deletes the user token for the specified user. Both userId and realm are required parameters. The token will be invalidated immediately and can no longer be used.
      operationId: deleteSecurityUsersUserToken
      parameters:
      - name: userId
        in: path
        description: The userId of the user to delete the token for
        required: true
        schema:
          type: string
      - name: realm
        in: path
        description: The realm of the user to delete the token for
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User token successfully deleted
        '400':
          description: User tokens are not enabled
        '403':
          description: Insufficient permissions to delete user token
        '404':
          description: User not found in realm or token not found
        '422':
          description: Invalid realm
        '500':
          description: Unexpected server error
  /v1/security/users/{userId}/{realm}/user-token-reset:
    delete:
      tags:
      - 'Security management: users'
      summary: Reset the user token for the given user
      description: Resetting the user token will invalidate the current token and force a new token to be created the next time it is accessed. This endpoint is deprecated, use DELETE /user-token instead.
      operationId: deleteSecurityUsersUserTokenReset
      parameters:
      - name: userId
        in: path
        description: The userId of the user to reset the token for
        required: true
        schema:
          type: string
      - name: realm
        in: path
        description: The realm of the user to reset the token for
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User token successfully reset
        '400':
          description: User tokens are not enabled
        '403':
          description: Insufficient permissions to reset user token
        '404':
          description: User not found
        '422':
          description: Invalid realm
      deprecated: true
components:
  schemas:
    ApiUser:
      required:
      - source
      - status
      - userId
      type: object
      properties:
        userId:
          minLength: 1
          type: string
          description: The userid which is required for login. This value cannot be changed.
        firstName:
          type:
          - string
          - 'null'
          description: The first name of the user.
        lastName:
          type:
          - string
          - 'null'
          description: The last name of the user.
        emailAddress:
          type:
          - string
          - 'null'
          description: The email address associated with the user.
          format: email
        source:
          minLength: 1
          type: string
          description: The source of the user. When creating user, if the source is "default", the local Nexus Security User will be created. If the source is anything but "default" (i.e., LDAP or SAML), a local LdapUser (or SamlUser) will be created and have the listed roles assigned to that user.
        status:
          type: string
          description: The user's status, e.g. active or disabled.
          enum:
          - active
          - locked
          - disabled
          - changepassword
        readOnly:
          type: boolean
          description: Indicates whether the user's properties could be modified by the Nexus Repository Manager. When false only roles are considered during update.
        roles:
          uniqueItems: true
          type: array
          description: The roles which the user has been assigned within Nexus.
          items:
            type: string
            description: The roles which the user has been assigned within Nexus.
        externalRoles:
          uniqueItems: true
          type: array
          description: The roles which the user has been assigned in an external source, e.g. LDAP group. These cannot be changed within the Nexus Repository Manager.
          items:
            type: string
            description: The roles which the user has been assigned in an external source, e.g. LDAP group. These cannot be changed within the Nexus Repository Manager.
    UserTokenXO:
      required:
      - created
      - nameCode
      type: object
      properties:
        userId:
          type: string
        realm:
          type: string
        nameCode:
          type: string
        passCode:
          type: string
        created:
          type: string
          format: date-time
        expires:
          type: string
          format: date-time
        isExpired:
          type: boolean
        createdByUserId:
          type: string
        createdByRealm:
          type: string
      xml:
        name: userToken
    ApiCreateUser:
      required:
      - emailAddress
      - firstName
      - lastName
      - password
      - status
      - userId
      type: object
      properties:
        userId:
          minLength: 1
          type: string
          description: The userid which is required for login. This value cannot be changed.
        firstName:
          minLength: 1
          type: string
          description: The first name of the user.
        lastName:
          minLength: 1
          type: string
          description: The last name of the user.
        emailAddress:
          minLength: 1
          type: string
          description: The email address associated with the user.
          format: email
        password:
          minLength: 1
          type: string
          description: The password for the new user.
        status:
          type: string
          description: The user's status, e.g. active or disabled.
          enum:
          - active
          - locked
          - disabled
          - changepassword
        roles:
          uniqueItems: true
          type: array
          description: The roles which the user has been assigned within Nexus.
          items:
            type: string
            description: The roles which the user has been assigned within Nexus.