api.raml

#%RAML 1.0
title: Password Manager Backend
version: 4
protocols: [ HTTPS ]
mediaType: application/json
securitySchemes:
  AuthzHttpOnlyCookie:
      type: x-cookie
      describedBy:
        headers:
          Cookie:
            description: |
              The access token is stored in a secure, HttpOnly cookie
            type: string
            example: access_token=your_secure_token_value
securedBy: [ AuthzHttpOnlyCookie ]
types:
  Config:
    type: object
    properties:
      idpName: string
      support:
        type: object
        properties:
          phone: string
          email: string
          url: string
          feedbackUrl: string
      passwordRules:
        type: object
        properties:
          minLength: integer
          maxLength: integer
          minScore: integer
          hibpEnable: boolean
    example:
      {
        "idpName": "Acme",
        "support": {
          "phone": "1-234-567-8901",
          "email": "support@example.com",
          "url": "http://support.example.com",
          "feedbackUrl": "feedback@example.com"
        },
        "passwordRules": {
          "minLength": 10,
          "maxLength": 255,
          "minScore": 3,
          "enableHIBP": true
          }
        }
      }
  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, email ]
      verified?: boolean
    example:
      value:
        {
          "id": "nFV7mQQJl3L0PB4kfS2tG1YYbmzT0Ghm",
          "type": "email",
          "value": "shep@gmail.com"
        }
  Mfa:
    type: object
    properties:
      id?: integer
      type:
        enum: [ backupcode, totp, webauthn ]
      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:37Z",
        "last_used_utc": "2018-09-07T17:47:06Z",
        "data": [
           "count": 9
        ]
      }
  MfaWebauthn:
    type: object
    properties:
      id?: integer
      type: string
      label?: string
      created_utc?: string
      last_used_utc?: string
      data?: array
    example:
      {
        "id": 1,
        "type": "webauthn",
        "label": "",
        "created_utc": "2018-09-07T17:46:37Z",
        "last_used_utc": "2018-09-07T17:47:06Z",
        "data": [
           {
             "id": 11,
             "mfa_id": 1,
             "key_handle_hash": "ABC123",
             "label": "Security Key-1",
             "created_utc": "2018-09-07T17:46:37Z",
             "last_used_utc": "2018-09-07T17:47:06Z"
           }
        ]
      }
  Webauthn:
    type: object
    properties:
      id: integer
      mfa_id: integer
      key_handle_hash: string
      label: string
      created_utc: string
      last_used_utc?: string
    example:
      {
        "id": 11,
        "mfa_id": 1,
        "key_handle_hash": "ABC123",
        "label": "My First Security Key",
        "created_utc": "2018-09-07T17:46:37Z",
        "last_used_utc": "2018-09-07T17:47:06Z"
      }
  PasswordMeta:
    type: object
    properties:
      last_changed: string
      expires: string
    example:
      {
        "last_changed": "2018-09-13T19:21:57Z",
        "expires": "2020-09-13T23:59:59Z"
      }
  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": "i****@s**.com"
          },
          {
            "type": "supervisor",
            "value": "a*******@s**.org"
          },
          {
            "id": a4a45eg5h6h7tjy8kaw4w33,
            "type": "email",
            "value": "j****@c*********.com"
          }
        ]
      }
  User:
    description: |
      A limited set of information describing a user account. Does not necessarily
      contain all of the properties in the personnel record, and may contain other
      non-personnel information.
    type: object
    properties:
      uuid: string
      first_name: string
      last_name: string
      idp_username: string
      email: string
      auth_type:
        enum: [ login, reset ]
      hide:
        enum: [ yes, no ]
      last_login: string
      password_meta?: PasswordMeta
      manager_email?: string
    example:
      {
        "uuid": "55b2447f-87f7-4286-8bd1-a7478f9dae38",
        "first_name": "John",
        "last_name": "Doe",
        "idp_username": "john_doe",
        "email": "john_doe@example.com",
        "auth_type": "login",
        "hide": "no",
        "last_login": "2018-09-13T19:21:57Z",
        "password_meta": {
          "last_changed": "2018-09-13T19:21:57Z",
          "expires":  "2020-09-13T23:59:59Z"
        }
        "manager_email": "manager@example.com"
      }
/auth:
  /login:
    get:
      securedBy: null
      queryParameters:
        ReturnTo:
          description: URL to return to after login or invite
          type: string
        ReturnToOnError?:
          description: URL to return to in case of expired invite
          type: string
        invite?:
          description: New user invite code
          type: string
      responses:
        302:
          description: >
            On successful login or invite, a redirection to `ReturnTo`. If `invite` was provided, but it has expired,
            this response will be a redirection to `ReturnToOnError` with no query string parameters.
          headers:
            location:
              description: redirect URL
              type: string
              example:
                https://idp-pw.org/profile/#
        400:
          description: Error or missing information in request.
    post:
      securedBy: null
      body:
        mediaType: application/x-www-form-urlencoded
        properties:
          SAMLResponse:
          RelayState:
  /logout:
    get:
      securedBy: null
      responses:
        200:
/config:
  get:
    securedBy: null
    description: Request various configuration parameters.
    responses:
      200:
        body:
          type: Config
      500:
        description: Backend configuration is missing one or more parameters.
/method:
  get:
    description: >
      Request a list of password recovery methods, including methods
      not yet verified.
    responses:
      200:
        body:
          type: Method[]
      500:
        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.
          body:
            type: Error
    delete:
      description: Delete a recovery method object.
      responses:
        204:
          description: Method has been deleted.
        404:
          description: Method not found.
        500:
          description: Delete failed.
    /verify:
      securedBy: null
      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.
          410:
            description: Expired verification code
          429:
            description: Too many verification attempts on this method.
          500:
            description: Database or other system error
    /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
      500:
        body:
          type: Error
  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
      409:
        description: >
          An MFA of the requested type already exists. Note that this would only
          be returned for 'totp' or 'webauthn'. The code types ('backupcode' and
          'manager') reuse the existing MFA and create new codes.
        body:
          type: Error
      400:
        description: Property `type` was omitted.
        body:
          type: Error
  /{mfaId}:
    put:
      description: Update an MFA object.
      body:
        properties:
          label: string
      responses:
        200:
          description: Object updated
          body:
            type: Mfa
        400:
          description: Property `label` was blank or omitted.
          body:
            type: Error
        404:
          description: Object not found
          body:
            type: Error
    delete:
      description: Delete an MFA object.
      responses:
        200:
          description: Object deleted
        404:
          description: Object not found
          body:
            type: Error
    /verify:
      put:
        description: Attempt to verify an MFA object.
        body:
          properties:
            value: string
        responses:
          200:
            description: MFA verified successfully.
            body:
              type: Mfa
          400:
            description: Property `value` was omitted or incorrect.
          429:
            description: Too many verify requests have been attempted.
      /registration:
        put:
          description: Verify the registration of a new mfa webauthn credential.
          body:
            properties:
              value: array
              label: string
            example: |
              {
                "value": {
                  "id":"abc123",
                  "rawId":"abc123",
                  "response":  {
                    "attestationObject":"abc123",
                    "clientDataJSON":"abc123"
                  },
                  "type":"public-key",
                  "clientExtensionResults":{},
                  "transports":["usb"]
                }
                "label": "Yubikey"
             }
          responses:
            200:
              description: Value provided passed verification
              body:
                type: MfaWebauthn
            400:
              description: >
                Value provided failed verification or was unacceptable for some
                other reason (such as current user's `employee_id` was not accepted).
              body:
                type: Error
            404:
              description: No MFA record found with that `id` and `employee_id`.
              body:
                type: Error
    /webauthn:
      /{webauthnId}:
        put:
          description: Update the label of a MFA webauthn credential.
          body:
            properties:
              label: string
            example: |
              {
                "label": "My First Security Key"
              }
          responses:
            200:
              description: Webauthn label successfully updated
              body:
                type: Webauthn
            400:
              description: Missing or blank label value or invalid employee_id
              body:
                type: Error
            403:
              description: Forbidden for user with auth_type not 'login'.
              body:
                type: Error
            404:
              description: >
                No MFA record found with that `mfa_id` or no webauthn
                record found with that `id` and that `mfa_id`.
              body:
                type: Error
            500:
              description: Internal server error
              body:
                type: Error
        delete:
          description: >
            Delete a webauthn credential from an MFA. If it is the last credential,
            the whole MFA will be deleted.
          responses:
            204:
              description: Successful deletion of record
            400:
              description: current user's employee_id was not accepted
              body:
                type: Error
            403:
              description: The MFA record was not of type webauthn
              body:
                type: Error
            404:
              description: >
                No MFA record found with that `mfa_id` or no webauthn
                record found with that `id` and that `mfa_id`.
              body:
                type: Error
            500:
              description: Unable to delete the webauthn credential or the MFA record
              body:
                type: Error
/password:
  put:
    description: Set a new password.
    body:
      properties:
        password:
          type: string
      example:
        {
          "password": "abc123!@*ABC"
        }
    responses:
      200:
        body:
          type: PasswordMeta
      400:
        description: A password was not provided or it does not pass validation.
        body:
          type: Error
      409:
        description: The requested password has been used too recently.
        body:
          type: Error
  get:
    description: Get password metadata.
    responses:
      200:
        body:
          type: PasswordMeta
  /assess:
    put:
      description: Assess whether a new password will pass all validation rules.
      body:
        properties:
          password: string
        example:
          {
            "password": "abc123!@#ABC"
          }
      responses:
        204:
          description: All validation rules pass.
        400:
          description: A password was not provided or it does not pass validation.
          body:
            type: Error
        409:
          description: The requested password has been used too recently.
          body:
            type: Error
/reset:
  post:
    securedBy: null
    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:
      securedBy: null
      description: Request the reset object by its id.
      responses:
        200:
          body:
            type: Reset
    put:
      securedBy: null
      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, 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.
          body:
            type: Error
        404:
          description: >
            The reset could not be found or the referenced Method has
            not been verified.
          body:
            type: Error
    /resend:
      put:
        securedBy: null
        description: Request to resend verification email.
        responses:
          200:
            body:
              type: Reset
          404:
            description: Reset could not be found.
            body:
              type: Error
    /validate:
      put:
        securedBy: null
        description: Validate reset code to complete password reset process
        body:
          properties:
            code: string
        responses:
          200:
            description: >
              Reset was validated. Subsequent API calls will use a http only cookie for the access token.
          400:
            description: >
              The provided code was incorrect.
          410:
            description: >
              The code has expired.
/site:
  /system-status:
    get:
      securedBy: null
      description: Check site status.
      responses:
        200:
          description: Site is operational.
/user:
  /me:
    description: Operations for currently-authenticated user.
    get:
      description: Request basic information for the user.
      responses:
        200:
          body:
            type: User
    put:
      description: >
        Limited options for updating the user record. If no
        properties are provided, no changes will be made.
      body:
        properties:
          hide?:
            enum: [ yes, no ]
      responses:
        200:
          description: User information after changes have been made.
          body:
            type: User