openapi: 3.0.0
info:
  version: v1
  title: Reset Password API
  description: >-
    Use the Reset Password API to manage NGINX Controller password
    recovery.
servers:
  - description: NGINX Controller API
    url: 'https://{{CONTROLLER_FQDN}}/api/v1'
paths:
  /platform/auth/password-recovery:
    post:
      tags:
        - Password
      summary: Request password reset
      description: >-
        Creates a password recovery code for user with given email
        and sends an email with reset link. The reset link is
        valid for an hour.
      operationId: requestResetPassword
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
            example:
              metadata:
                name: user@nginx.com
      responses:
        '204':
          description: >-
            Successfully created the password recovery code. No
            content was returned.
  '/platform/auth/password-recovery/{code}':
    put:
      tags:
        - Password
      summary: Password reset
      description: >-
        Check if the new password satisfies the policy constraints
        and update the password for the user associated with the
        recovery code.
      operationId: resetPassword
      parameters:
        - $ref: '#/components/parameters/code'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPassword'
            example:
              desiredState:
                password: NewPaw12!
              metadata:
                name: user@nginx.com
      responses:
        '204':
          description: >-
            Successfully updated the password for the user. No
            content was returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
components:
  parameters:
    code:
      in: path
      name: code
      schema:
        type: string
        minLength: 1
      required: true
      description: |
        The password recovery code.
  responses:
    BadRequest:
      description: >
        Bad input parameter, or possibly a bad URI. Password does
        not follow the policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 1111
            message: >-
              The user password doesn't meet the password
              requirements. Passwords must be between 8-64
              characters in length and contain at least 1 letter
              and 1 number. When updating a password, the new
              password cannot be the same as the old password.
              Dictionary words, mangled dictionary words, or
              systematic passwords like '1234567a' are not
              allowed.
    Internal:
      description: >
        The request cannot be processed because of an internal
        server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
          example:
            code: 1111
            message: >-
              An internal error occurred while updating the
              password. Try again later. If the problem persists,
              contact the system administrator.
  schemas:
    ResetPasswordRequest:
      type: object
      required:
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/ResourceMeta'
    ResetPassword:
      type: object
      required:
        - desiredState
        - metadata
      properties:
        metadata:
          $ref: '#/components/schemas/ResourceMeta'
        desiredState:
          type: object
          required:
            - password
          properties:
            password:
              type: string
              format: password
              example: TestImpl45!
              minLength: 8
              maxLength: 64
              description: >
                The user's password must meet the following
                requirements:
                  - Length must be between 8 and 64 characters
                  - Must contain at least 1 letter
                  - Must contain at least 1 number
                  - Must be different from the old password
                  - Dictionary words, mangled dictionary words, or systematic passwords like '1234567a' are not allowed.
    SelfLinks:
      type: object
      description: >
        The SelfLinks object contains a link from the resource to
        itself.

        This object is used only in responses.
      properties:
        rel:
          type: string
          example: /api/v1/services/environments/prod
          description: >
            `rel` contains the complete path fragment of a URI and
            can be used

            to construct a query to the object.
    ResourceMeta:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: >-
            ^[^A-Z\s\x00-\x1f\x60\x7f\;\*\"\[\]\{\}\\\/%\?:=&\~\^|#<>]+$
          not:
            type: string
            enum:
              - .
              - ..
          minLength: 1
          maxLength: 1024
          example: resource-name
          description: >
            Resource name is a unique identifier for a resource
            within the context of a namespace.

            Resource names must conform to [RFC 1738 Section
            2.2](https://www.ietf.org/rfc/rfc1738.txt) and have a
            valid syntax for email addresses. The following rules
            are enforced:


            - do not utilize URL encoding;

            - do not include spaces;

            - do not use uppercase characters, for example, 'A-Z';
            extended character sets are supported;

            - do not use the following characters: `"`, `*`, `:`,
            `;`, `/`, `\`, `%`, `?`, `hash`, `=`, `&`, `|`, `~`,
            `^`, `{`, `}`, `[`, `]`, `<`, `>`;

            - cannot start or end with an `@` sign;

            - cannot be only `.` or `..`


            For example: For a collection resource located at


            `https://controller.example.com/api/v1/services/apps/shopping_@1`


            the resource name is "shopping_@1".
        displayName:
          type: string
          example: My Display Name
          description: >
            `displayName` is a user friendly resource name. It can
            be used to define 

            a longer, and less constrained, name for a resource.


            Display names:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        description:
          type: string
          example: >-
            This is a sample description string. It provides
            information about the resource.
          description: >
            `description` is a free-form text property. You can
            use it to provide information that helps 

            to identify the resource.


            Descriptions:


            - are optional (defaults to an empty string if no
            value is provided),

            - do not have to be unique, 

            - cannot be assigned by the server.
        kind:
          type: string
          example: <collection>-<object>
          description: >
            Kind is a string representation of an API resource's
            data type.

            It is assigned by the server and cannot be changed. 


            When creating a `kind`, the server uses hyphens to
            connect word segments; 

            singleton and collection item resources are not
            pluralized.
        uid:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          description: >
            Unique Identifier (UID)


            UID is a unique identifier in time and space for a
            resource. 

            When you create a resource, the server assigns a UID
            to the resource.


            Refer to [IETF RFC
            4122](https://tools.ietf.org/html/rfc4122) for more
            information.
        tags:
          type: array
          items:
            type: string
          example:
            - production_public
            - dev
            - new_app
            - us-west-1
            - emea
          description: >
            You can assign `tags` to a resource as a way to help
            map, scope, 

            and organize resources. 


            The system uses tag selectors to specify selection
            criteria that 

            match resources that have particular tags.
        ref:
          type: string
          example: /services/environments/prod
          description: >
            The `ref` field contains a reference to another NGINX
            Controller resource.
        links:
          $ref: '#/components/schemas/SelfLinks'
        createTime:
          type: string
          format: date-time
          example: '2019-07-29T09:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was created.


            Create time is not guaranteed to be set in
            "happens-before" order

            across separate operations.


            In JSON format, `create_time` type is encoded as a
            string in the

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).


            For example: 2018-04-01T01:30:15.01Z


            Create Time is assigned by the server and cannot be
            changed.
        updateTime:
          type: string
          format: date-time
          example: '2019-07-29T10:12:33.001Z'
          description: >
            A timestamp that represents the server time when the
            resource was last modified.


            Resources that have never been updated do not have an
            `update_time` stamp.


            The default value for resources that have never been
            updated is the local 

            language-specific equivalent of "null".


            In JSON format, `update_time` type is encoded as a
            string as described in 

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
    ErrorDetail:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          example: >-
            Error doing <action>: <reason for error>. This can
            lead to <potential consequences>. Try <action> to
            resolve the issue.
          description: >
            A detailed error message returned by the server. 


            These messages contain the following information,
            where applicable:


            - What happened.

            - Why it happened.

            - What the consequences are (if any).

            - Recommended action to take to resolve the issue.
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          example: Error doing <action>.
          description: >
            A human-readable message, in English, that describes
            the error.
        code:
          type: integer
          example: 1234567
          description: >
            A numeric error code that can be used to identify
            errors for support purposes.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'