Sonatype Nexus Security management: users API

openapi: 3.0.1
info:
  contact:
    name: Sonatype Community Maintainers
    url: https://github.com/sonatype-nexus-community
  description: This documents the available APIs into [Sonatype Nexus Repository Manager](https://www.sonatype.com/products/sonatype-nexus-repository) as of version 3.91.0-07.
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: 'Sonatype Nexus Repository Manager assets Security management: users API'
  version: 3.91.0-07
servers:
- url: /service/rest/
security:
- BasicAuth: []
tags:
- name: 'Security management: users'
paths:
  /v1/security/users:
    get:
      operationId: getUsers
      parameters:
      - description: An optional term to search userids for.
        in: query
        name: userId
        schema:
          type: string
      - description: An optional user source to restrict the search to.
        in: query
        name: source
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ApiUser'
                type: array
          description: successful operation
        '400':
          content: {}
          description: Password was not supplied in the body of the request
        '403':
          content: {}
          description: The user does not have permission to perform the operation.
      summary: Retrieve a list of users. For SAML user sources a limit of 1000 users will be applied.
      tags:
      - 'Security management: users'
    post:
      operationId: createUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateUser'
        description: A representation of the user to create.
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUser'
          description: successful operation
        '400':
          content: {}
          description: Password was not supplied in the body of the request
        '403':
          content: {}
          description: The user does not have permission to perform the operation.
      summary: Create a new user in the default source.
      tags:
      - 'Security management: users'
      x-codegen-request-body-name: body
  /v1/security/users/{userId}:
    delete:
      operationId: deleteUser
      parameters:
      - description: The userid the request should apply to.
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: The realm the request should apply to.
        in: query
        name: realm
        schema:
          type: string
      responses:
        '400':
          content: {}
          description: There was problem deleting a user. Consult the response body for more details
        '403':
          content: {}
          description: The user does not have permission to perform the operation.
        '404':
          content: {}
          description: User or user source not found in the system.
      summary: Delete a user.
      tags:
      - 'Security management: users'
    put:
      operationId: updateUser
      parameters:
      - description: The userid the request should apply to.
        in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUser'
        description: A representation of the user to update.
        required: false
      responses:
        '204':
          content: {}
          description: Success
        '400':
          content: {}
          description: Password was not supplied in the body of the request
        '403':
          content: {}
          description: The user does not have permission to perform the operation.
        '404':
          content: {}
          description: User or user source not found in the system.
      summary: Update an existing user.
      tags:
      - 'Security management: users'
      x-codegen-request-body-name: body
  /v1/security/users/{userId}/change-password:
    put:
      operationId: changePassword
      parameters:
      - description: The userid the request should apply to.
        in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        description: The new password to use.
        required: false
      responses:
        '204':
          content: {}
          description: Success
        '400':
          content: {}
          description: Password was not supplied in the body of the request
        '403':
          content: {}
          description: The user does not have permission to perform the operation.
        '404':
          content: {}
          description: User not found in the system.
      summary: Change a user's password.
      tags:
      - 'Security management: users'
      x-codegen-request-body-name: body
  /v1/security/users/{userId}/{realm}/user-token:
    delete:
      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: delete_4
      parameters:
      - description: The userId of the user to delete the token for
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: The realm of the user to delete the token for
        in: path
        name: realm
        required: true
        schema:
          type: string
      responses:
        '204':
          content: {}
          description: User token successfully deleted
        '400':
          content: {}
          description: User tokens are not enabled
        '403':
          content: {}
          description: Insufficient permissions to delete user token
        '404':
          content: {}
          description: User not found in realm or token not found
        '422':
          content: {}
          description: Invalid realm
        '500':
          content: {}
          description: Unexpected server error
      summary: Delete the user token for the given user.
      tags:
      - 'Security management: users'
    get:
      description: Retrieves metadata for an existing user token. Both userId and realm are required parameters. The passCode is never returned in this response.
      operationId: get_3
      parameters:
      - description: The userId of the user to get the token for
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: The realm of the user to get the token for
        in: path
        name: realm
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenXO'
          description: User token metadata retrieved successfully
        '400':
          content: {}
          description: User tokens are not enabled
        '403':
          content: {}
          description: Insufficient permissions to view user token
        '404':
          content: {}
          description: User not found in realm or token not found
        '422':
          content: {}
          description: Invalid realm
        '500':
          content: {}
          description: Unexpected server error
      summary: Get user token metadata for the given user.
      tags:
      - 'Security management: users'
    post:
      description: Creates a new user token for the specified user. Both userId and realm are required parameters.
      operationId: create_3
      parameters:
      - description: The userId of the user to create the token for
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: The realm of the user to create the token for
        in: path
        name: realm
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenXO'
          description: User token successfully created
        '400':
          content: {}
          description: User tokens are not enabled
        '403':
          content: {}
          description: Insufficient permissions to create user token
        '404':
          content: {}
          description: User not found in realm
        '409':
          content: {}
          description: User token already exists for this user and realm
        '422':
          content: {}
          description: Invalid realm
        '500':
          content: {}
          description: Unexpected server error
      summary: Create a user token for the given user.
      tags:
      - 'Security management: users'
  /v1/security/users/{userId}/{realm}/user-token-reset:
    delete:
      deprecated: true
      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: reset
      parameters:
      - description: The userId of the user to reset the token for
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: The realm of the user to reset the token for
        in: path
        name: realm
        required: true
        schema:
          type: string
      responses:
        '204':
          content: {}
          description: User token successfully reset
        '400':
          content: {}
          description: User tokens are not enabled
        '403':
          content: {}
          description: Insufficient permissions to reset user token
        '404':
          content: {}
          description: User not found
        '422':
          content: {}
          description: Invalid realm
      summary: Reset the user token for the given user.
      tags:
      - 'Security management: users'
components:
  schemas:
    ApiCreateUser:
      properties:
        emailAddress:
          description: The email address associated with the user.
          type: string
        firstName:
          description: The first name of the user.
          type: string
        lastName:
          description: The last name of the user.
          type: string
        password:
          description: The password for the new user.
          type: string
        roles:
          description: The roles which the user has been assigned within Nexus.
          items:
            type: string
          type: array
          uniqueItems: true
        status:
          description: The user's status, e.g. active or disabled.
          enum:
          - active
          - locked
          - disabled
          - changepassword
          type: string
        userId:
          description: The userid which is required for login. This value cannot be changed.
          type: string
      required:
      - status
      type: object
    UserTokenXO:
      properties:
        created:
          format: date-time
          type: string
        createdByRealm:
          type: string
        createdByUserId:
          type: string
        expires:
          format: date-time
          type: string
        isExpired:
          type: boolean
        nameCode:
          type: string
        passCode:
          type: string
        realm:
          type: string
        userId:
          type: string
      required:
      - created
      - nameCode
      type: object
      xml:
        name: userToken
    ApiUser:
      properties:
        emailAddress:
          description: The email address associated with the user.
          type: string
        externalRoles:
          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
          type: array
          uniqueItems: true
        firstName:
          description: The first name of the user.
          type: string
        lastName:
          description: The last name of the user.
          type: string
        readOnly:
          description: Indicates whether the user's properties could be modified by the Nexus Repository Manager. When false only roles are considered during update.
          type: boolean
        roles:
          description: The roles which the user has been assigned within Nexus.
          items:
            type: string
          type: array
          uniqueItems: true
        source:
          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.
          type: string
        status:
          description: The user's status, e.g. active or disabled.
          enum:
          - active
          - locked
          - disabled
          - changepassword
          type: string
        userId:
          description: The userid which is required for login. This value cannot be changed.
          type: string
      required:
      - status
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
x-original-swagger-version: '2.0'