v1auth contextCredential management
Authenticator app
Binding a TOTP authenticator — issuing the secret and checking the first code.
An authenticator app (TOTP) is a second factor. Each account can bind exactly one.
Endpoints
| Method | Path | Purpose | Step-up |
|---|---|---|---|
POST | /v1/auth/credentials/authenticator/options | Issue the secret | max_age=300 |
POST | /v1/auth/credentials/authenticator | Check the first code, then persist | None |
Step one: issue the secret
No request body.
{
"success": true,
"secret": "JBSWY3DPEHPK3PXP",
"otpauth_uri": "otpauth://totp/MuoCeon:alice?secret=JBSWY3DPEHPK3PXP&issuer=MuoCeon",
"expires_in": 300
}The server returns only the otpauth:// URI, never a rendered QR image: encoding the image belongs on the client, and doing it server-side would pass a one-time secret through an extra encoding round-trip.
Step two: confirm
| Parameter | Type | Required | Notes |
|---|---|---|---|
code | string | ✅ | The code currently shown by the app, 4–16 chars |
{ "success": true, "credential": { "id": "cred_...", "type": "authenticator" } }Why check a code first
Verifying once before persisting surfaces a pairing mistake at binding time instead of at the next sign-in. The secret stays readable until a code matches, so a mistyped code can be retried with the same secret rather than forcing the user to scan again.
Related
- Using the app to sign in: Verification challenges
- Fallback when the app is lost: Recovery codes