Versions Compared

Old Version 11

changes.mady.by.user Marco Marasca

Saved on

compared with

New Version Current

changes.mady.by.user Marco Marasca

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

API

Request

Response

Description

POST /2fa/enroll

Code Block
languagejson
{
"type": "totp"
}
Code Block
languagejson
{
"id": <id of the generated secret>,
"type": "totp",
"secret": "<Base64 encoded secret>",
"secretBase32": "<Base32 encoded version of the secret>"
"alg": "SHA1",
"digits": 6,
"period": 30
}

Initiate the enrollment for the user to 2FA.

The server generates a shared secret to use with an OTP application that is sent back to the user.

The client can generate a QR code for convenience so that the user can scan the secret when adding it to the OTP application (e.g. google authenticator). The URL to embed in the QR code can follow this format: https://github.com/google/google-authenticator/wiki/Key-Uri-Format#issuer .

For example: otpauth://totp/Synapse:alice@google.com?secret=<secretBase32>&issuer=Synapse%20Prod&algorithm=SHA1&digits=6&period=30.

Note that the endpoint can be invoked even if the user has 2FA already enabled.

The server will re-generate a secret that is not used until it is enabled, this allows the user to reset the 2FA without affecting existing 2FA.

POST /2fa

Code Block
languagejson
{
"secretId": <id from enroll API>,
"totp": <totp from app>
}
Code Block
languagejson
{
  "status": "enabled"
}

Enable 2FA for the user, uses the secret that was generated from the enroll API.

Note that the server will use only one secret to verify TOTPs.

This backend will replace other 2FA secrets already enabled if the request is successful.

POST /2fa/recovery_codes

Code Block
languagejson
{
  "codes": ["abc", "efg"]
}

Re-generates a set of recovery codes (we can provide at least 10 codes).

The codes are a one-time use code that the user can use to recover access to their account.

This endpoint will re-generate the codes on each call and associate them with the currently enabled 2FA.

The generated codes are hashed and never retrieved again.

Note that the user can end up using all of the recovery codes, in this case we should warn the user (maybe an email, or a notification in the browser?) that new codes should be re-generated.

If 2FA is not enabled the API will return a 400.

DELETE /2fa

Disable 2FA for the user.

If 2FA is not enabled the API will return a 400.

GET /2fa

Code Block
languagejson
{
  "status": "enabled"
}

Allows to fetch the current status of 2fa for the user.

...

API

Request

Response

Description

/2fa/token

Code Block
languagejson
{
 "2fa_token": <token received in the 401 mfa_required response>,
 "otp_type": "totp",
 "otp_code": <totp from app>
}
Code Block
languagejson
{
 "access_token": "<the access token that would be obtain from authentication>"
}

Allows to obtain an access token in exchange from the 2fa_token received from a 401 with error_code=mfa_required and the totp that the user inputs.

The otp_type parameter can be one of [totp, recovery_codes], the value of the otp_code is treated as the generated totp or a recovery code according to the type.

...