<commit_before>#%RAML 1.0
title: Password API
version: v3
baseUri: http://idp-pw-api.local:8080
protocols: [ HTTPS ]
mediaType: application/json
securitySchemes:
  AuthzBearerToken:
      type: x-{other}
      describedBy:
        headers:
          Authorization:
            type: string
            example: Bearer gwgyxgf0vbuwYrI60sbbxLM3U1Jjw2lyvG53Kjjy9cq
securedBy: [ AuthzBearerToken ]
types:
  Error:
    type: object
    properties:
      name: string
      message: string
      code: integer
      status: integer
    example:
      {
        "name": "Bad Request",
        "message": "Unable to update password. If this password has been used before please use something different.",
        "code": 1469194882,
        "status": 409
      }
  Method:
    type: object
    properties:
      id?: string
      value: string
      type:
        enum: [ primary, supervisor, spouse, email ]
      verified?: boolean
    example:
      {
        "id": "nFV7mQQJl3L0PB4kfS2tG1YYbmzT0Ghm",
        "type": "email",
        "value": "<EMAIL>"
      }
  Mfa:
    type: object
    properties:
      id?: integer
      type:
        enum: [ backupcode, totp, u2f ]
      label?: string
      created_utc?: string
      last_used_utc?: string
      data?: array
    example:
      {
        "id": 1,
        "type": "backupcode",
        "label": "a_label",
        "created_utc": "2018-09-07T17:46:37+00:00",
        "last_used_utc": "2018-09-07T17:47:06+00:00",
        "data": [
           "count": 9
        ]
      }
  PasswordMeta:
    type: object
    properties:
      last_changed: string
      expires: string
    example:
      {
        "last_changed": "2018-09-13T19:21:57+00:00",
        "expires": "2020-09-13T23:59:59+00:00"
      }
  Reset:
    description: |
      An object holding the verified emails that can be used for performing
      a password reset. The addresses in the response are
      masked for privacy.
    type: object
    properties:
      uid: string
      methods: Method[]
    example:
      {
        "uid": 123asdf123lkjfsdfw23,
        "methods": [
          {
            "type": "primary",
            "value": "<EMAIL>"
          },
          {
            "type": "spouse",
            "value": "a*******<EMAIL>"
          },
          {
            "type": "supervisor",
            "value": "a*******@s**.org"
          },
          {
            "id": a4a45eg5h6h7tjy8kaw4w33,
            "type": "email",
            "value": "<EMAIL>"
          }
        ]
      }

/auth:
  /login:
    get:
      queryParameters:
        ReturnTo:
          description: URL to return to after login
          type: string
      responses:
        302:
          description: Redirection to login page
    post:
      queryParameters:
        ReturnTo:
          description: URL to return to after login
          type: string
      responses:
        302:
          description: Redirection to login page
  /logout:
    get:
      responses:
        200:
/method:
  get:
    description: |
      Request a list of password recovery methods, including methods
      not yet verified.
    responses:
      200:
        body:
          type: Method[]
      400:
        description: User not found in personnel database.
  post:
    description: |
      Create a new password recovery method. The creation of a method
      is not completed until the following verification call is made.
      Unverified Methods will automatically expire if not verified
      within a certain amount of time.
    body:
      properties:
        value: string
    responses:
      200:
        body:
          type: Method
      400:
        description: Missing parameter
      409:
        description: New method matches an already existing verified method
      500:
        description: Database or other system error
  /{methodId}:
    get:
      description: Request a single verified password recovery method.
      responses:
        200:
          body:
            type: Method
        404:
          description: Method not found.
    put:
      description: Attempt to verify a recovery method.
      body:
        properties:
          code: string
      responses:
        200:
          body:
            type: Method
        400:
          description: Submitted code was incorrect or missing.
        404:
          description: Method not found.
        429:
          description: Too many verification attempts on this method.
        500:
          description: Database or other system error
    delete:
      description: Delete a recovery method object.
      responses:
        204:
          description: Method has been deleted.
        404:
          description: Method not found.
        500:
          description: Delete failed.
    /resend:
      put:
        description: Resend recovery verification message.
        responses:
          204:
            description: Message sent.
          400:
            description: Method already verified.
          500:
            description: Resend failed.
/mfa:
  get:
    description: Request a list of MFA objects for logged in user.
    responses:
      200:
        body:
          type: Mfa
  post:
    description: |
      Create a new MFA object. Only properties `type` and `label` are
      needed in the request.
    body:
      type: Mfa
    responses:
      200:
        description: |
          MFA object created. Only `id` and `data` are in the response.
          If `type` is `backupcode` then `data` is populated with the
          backup codes.
        body:
          type: Mfa
      400:
        description: Property `type` was omitted.
  /{mfaId}:
    delete:
      description: Delete an MFA object.
      responses:
        200:
          description: Object deleted
    /verify:
      post:
        description: Attempt to verify an MFA object.
        body:
          properties:
            value: string
        responses:
          204:
            description: MFA verified successfully.
          400:
            description: Property `value` was omitted or incorrect.
/password:
  put:
    description: Set a new password.
    body:
      properties:
        password:
          type: string
      example:
        {
          "password": "<PASSWORD>"
        }
    responses:
      200:
        body:
          type: PasswordMeta
      409:
        description: The requested password has been used too recently.
        body:
          type: Error
  get:
    description: Get password metadata.
    responses:
      200:
        body:
          type: PasswordMeta
/reset:
  post:
    description: |
      Initiate a password reset.
      Sends reset email to primary email address with a link like
      `https://idp-pw.local/#/recovery/verify/{resetUid}/{code}`
      Responds with id of reset object and all available email addresses
      for the user.
    body:
      properties:
        username:
          type: string
    responses:
      200:
        body:
          type: Reset
  /{resetId}:
    get:
      description: Request the reset object by its id.
      responses:
        200:
          body:
            type: Reset
    put:
      description: |
        Update the reset to use a different email. If `type` is `email`,
        then this request is for an alternate recovery Method, and
        `methodId` is required.
      body:
        properties:
          type:
            enum: [ primary, supervisor, spouse, email ]
          methodId?: string
      responses:
        200:
          body:
            type: Reset
        400:
          description: |
            The reset `type` was not provided or is not valid, or the
            `methodId` parameter was not provided when required.<commit_msg>Added 'verification_token' parameter to reset in RAML file<commit_after>#%RAML 1.0
title: Password API
version: v3
baseUri: http://idp-pw-api.local:8080
protocols: [ HTTPS ]
mediaType: application/json
securitySchemes:
  AuthzBearerToken:
      type: x-{other}
      describedBy:
        headers:
          Authorization:
            type: string
            example: Bearer gwgyxgf0vbuwYrI60sbbxLM3U1Jjw2lyvG53Kjjy9cq
securedBy: [ AuthzBearerToken ]
types:
  Error:
    type: object
    properties:
      name: string
      message: string
      code: integer
      status: integer
    example:
      {
        "name": "Bad Request",
        "message": "Unable to update password. If this password has been used before please use something different.",
        "code": 1469194882,
        "status": 409
      }
  Method:
    type: object
    properties:
      id?: string
      value: string
      type:
        enum: [ primary, supervisor, spouse, email ]
      verified?: boolean
    example:
      {
        "id": "nFV7mQQJl3L0PB4kfS2tG1YYbmzT0Ghm",
        "type": "email",
        "value": "<EMAIL>"
      }
  Mfa:
    type: object
    properties:
      id?: integer
      type:
        enum: [ backupcode, totp, u2f ]
      label?: string
      created_utc?: string
      last_used_utc?: string
      data?: array
    example:
      {
        "id": 1,
        "type": "backupcode",
        "label": "a_label",
        "created_utc": "2018-09-07T17:46:37+00:00",
        "last_used_utc": "2018-09-07T17:47:06+00:00",
        "data": [
           "count": 9
        ]
      }
  PasswordMeta:
    type: object
    properties:
      last_changed: string
      expires: string
    example:
      {
        "last_changed": "2018-09-13T19:21:57+00:00",
        "expires": "2020-09-13T23:59:59+00:00"
      }
  Reset:
    description: |
      An object holding the verified emails that can be used for performing
      a password reset. The addresses in the response are
      masked for privacy.
    type: object
    properties:
      uid: string
      methods: Method[]
    example:
      {
        "uid": 123asdf123lkjfsdfw23,
        "methods": [
          {
            "type": "primary",
            "value": "<EMAIL>"
          },
          {
            "type": "spouse",
            "value": "<EMAIL>"
          },
          {
            "type": "supervisor",
            "value": "<EMAIL>"
          },
          {
            "id": a4a45eg5h6h7tjy8kaw4w33,
            "type": "email",
            "value": "<EMAIL>"
          }
        ]
      }

/auth:
  /login:
    get:
      queryParameters:
        ReturnTo:
          description: URL to return to after login
          type: string
      responses:
        302:
          description: Redirection to login page
    post:
      queryParameters:
        ReturnTo:
          description: URL to return to after login
          type: string
      responses:
        302:
          description: Redirection to login page
  /logout:
    get:
      responses:
        200:
/method:
  get:
    description: |
      Request a list of password recovery methods, including methods
      not yet verified.
    responses:
      200:
        body:
          type: Method[]
      400:
        description: User not found in personnel database.
  post:
    description: |
      Create a new password recovery method. The creation of a method
      is not completed until the following verification call is made.
      Unverified Methods will automatically expire if not verified
      within a certain amount of time.
    body:
      properties:
        value: string
    responses:
      200:
        body:
          type: Method
      400:
        description: Missing parameter
      409:
        description: New method matches an already existing verified method
      500:
        description: Database or other system error
  /{methodId}:
    get:
      description: Request a single verified password recovery method.
      responses:
        200:
          body:
            type: Method
        404:
          description: Method not found.
    put:
      description: Attempt to verify a recovery method.
      body:
        properties:
          code: string
      responses:
        200:
          body:
            type: Method
        400:
          description: Submitted code was incorrect or missing.
        404:
          description: Method not found.
        429:
          description: Too many verification attempts on this method.
        500:
          description: Database or other system error
    delete:
      description: Delete a recovery method object.
      responses:
        204:
          description: Method has been deleted.
        404:
          description: Method not found.
        500:
          description: Delete failed.
    /resend:
      put:
        description: Resend recovery verification message.
        responses:
          204:
            description: Message sent.
          400:
            description: Method already verified.
          500:
            description: Resend failed.
/mfa:
  get:
    description: Request a list of MFA objects for logged in user.
    responses:
      200:
        body:
          type: Mfa
  post:
    description: |
      Create a new MFA object. Only properties `type` and `label` are
      needed in the request.
    body:
      type: Mfa
    responses:
      200:
        description: |
          MFA object created. Only `id` and `data` are in the response.
          If `type` is `backupcode` then `data` is populated with the
          backup codes.
        body:
          type: Mfa
      400:
        description: Property `type` was omitted.
  /{mfaId}:
    delete:
      description: Delete an MFA object.
      responses:
        200:
          description: Object deleted
    /verify:
      post:
        description: Attempt to verify an MFA object.
        body:
          properties:
            value: string
        responses:
          204:
            description: MFA verified successfully.
          400:
            description: Property `value` was omitted or incorrect.
/password:
  put:
    description: Set a new password.
    body:
      properties:
        password:
          type: string
      example:
        {
          "password": "<PASSWORD>"
        }
    responses:
      200:
        body:
          type: PasswordMeta
      409:
        description: The requested password has been used too recently.
        body:
          type: Error
  get:
    description: Get password metadata.
    responses:
      200:
        body:
          type: PasswordMeta
/reset:
  post:
    description: |
      Initiate a password reset.
      Sends reset email to primary email address with a link like
      `https://idp-pw.local/#/recovery/verify/{resetUid}/{code}`
      Responds with id of reset object and all available email addresses
      for the user.
    body:
      properties:
        username:
          type: string
        verification_token?:
          description: |
            ReCAPTCHA verification token. Required if app is configured
            to require ReCAPTCHA for password reset.
          type: string
    responses:
      200:
        body:
          type: Reset
  /{resetId}:
    get:
      description: Request the reset object by its id.
      responses:
        200:
          body:
            type: Reset
    put:
      description: |
        Update the reset to use a different email. If `type` is `email`,
        then this request is for an alternate recovery Method, and
        `methodId` is required.
      body:
        properties:
          type:
            enum: [ primary, supervisor, spouse, email ]
          methodId?: string
      responses:
        200:
          body:
            type: Reset
        400:
          description: |
            The reset `type` was not provided or is not valid, or the
            `methodId` parameter was not provided when required.
{'fraction_non_alphanumeric': 0.07826583724768313, 'fraction_numerical': 0.029706741145106005, 'mean_word_length': 1.6354968216794914, 'pattern_counts': {'":': 56, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5943480', 'n_tokens_mistral': 4552, 'n_tokens_neox': 4264, 'n_words': 1450}