TOTP 2 Factor implementation

Managing Authenticators

Requesting a secret.

GET /users/:id/authenticator.

This request will generate a TOTP secret key as well as a totp:// URL that can be encoded as a QR code to be displayed by the user-agent.

• (The user agent should also display the secret key by itself for users who for whatever reason can not utilise the QR code).

This generation could technically happen on the user agent, but this endpoint is provided as a convenience.

Response Body:

{
  "data": {
    "type": "generated-authenticators",
    "id": "e2132a16-971d-451c-bbf6-4f8047e67883",
    "attributes": {
      "secret": "HUNTER2",
      "dataUri": "otpauth://totp/Fuel%20Rats:mail@example.com?secret=HUNTER2&period=30&digits=6&algorithm=SHA1&issuer=Fuel%20Rats"
    }
  }
}

The user should be prompted by the user-agent to add the 2-factor code to their application of choice and asked to provide a generated code from the application.

Linking the authenticator

POST /users/:id/authenticator.

The user-agent should send the secret it received in the previous request, the generated token by the user, and a description of the authentication device provided by the user. Request Body:

{
  "data": {
    "type": "authenticators",
    "attributes": {
      "token": "012345",
      "secret": "hunter2",
      "description": "John's Phone"
    }
  }
}

Responses: 201 Created: The authenticator was successfully added 409 Conflict: An authenticator is already attached to this account 422 Unprocessable Entity: A field in the request body is invalid. The field will be provided in the JSONAPI error "pointer" attribute. This error will be provided with a pointer to "/data/attributes/token" if the user provides a generated token that does not match with the secret.

Deleting authenticator

DELETE /users/:id/authenticator

This will unlink the authenticator from the user's account. A header containing a valid code generated by the 2-factor authentication app must be provided.
Headers:

x-verify: 012345

Authenticating

The TOTP 2-factor is an extension of the existing session verification system.
When an ROPC login is attempted, no valid session is found, and the user has a 2-factor authenticator attached to their account, the API will return a 403 "authenticator-required" error, instead of the 403 "verification-required" error provided for users that need an email verification.

The user agent should then prompt the user for their 2-factor authenticator code and retry the request with the generated code in the body "verify" field, same as for an email-based code.

If an ROPC login request is made with an invalid 2-factor code, the API will return an OAuth invalid_request error pointing to the "verify" field.