Skip to main content

TOTP Configuration

Introduction#

Concept#

TOTP is used in our 2FA mechanism.

It must register on a external TOTP App via a QR Code.

TOTP#

Configure TOTP#

This initiates a TOTP Enrollment to attach TOTP secret to an identity

Request#

GET https://api.misakey.com/identities/:id/totp/enroll

Cookies:

  • accesstoken (opaque token) (ACR >= 1): mid claim as the identity id.
  • tokentype (optional): must be bearer.

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

  • id (uuid string): the identity unique id.

Response#

Code:

HTTP 200 OK

JSON Body:

{
"id": "<uuid string>",
"base64_image": "<b64 image>"
}
  • id: an uuid to identify the enrollment flow
  • base64_image: the QR code image encoded in base64

Finish TOTP enrollment#

This completes a TOTP Enrollment flow.

Request#

POST https://api.misakey.com/identities/:id/totp/enroll

Cookies:

  • accesstoken (opaque token) (ACR >= 1): mid claim as the identity id.
  • tokentype (optional): must be bearer.

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

  • id (uuid string): the identity unique id.

JSON Body:

{
"id": "<uuid string>",
"code": "<string>"
}
  • id: the unique id identifying the enrollment flow
  • code: the code returned by the external app when registering via the QR code

Response#

Code:

HTTP 200 OK

JSON Body:

{
"recovery_codes": [
"<string>",
"<string>"
]
}
  • recovery_codes: a set of one time use codes that can be used instead of the code during auth flow

Regenerate recovery codes#

This allows a user to regenerate their set of recovery codes.

It erases the old set.

Request#

POST https://api.misakey.com/identities/:id/totp/recovery-codes

Cookies:

  • accesstoken (opaque token) (ACR >= 3): mid claim as the identity id.
  • tokentype (optional): must be bearer.

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

  • id (uuid string): the identity unique id.

Response#

Code:

HTTP 200 OK

JSON Body:

{
"recovery_codes": [
"<string>",
"<string>"
]
}
  • recovery_codes: a set of one time use codes that can be used instead of the code during auth flow

Delete TOTP Secret#

This route deletes the unique identity secret.

The identity must not have mfa_method configured to totp.

Request#

DELETE https://api.misakey.com/identities/:id/totp

Cookies:

  • accesstoken (opaque token) (ACR >= 2): mid claim as the identity id owning the credential.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks

Path Parameters:

  • id (string) (uuid): The identity id.

Response#

Code:

HTTP 204 No Content