Skip to content
Authrim

Start TOTP signup.

POST
/api/auth/totp/signup/options
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/auth/totp/signup/options \
  --header 'Content-Type: application/json' \
  --data '{ "email": "user@example.com", "name": "Example User", "label": "Authenticator app", "custom_fields": {} }'

Creates a short-lived TOTP enrollment challenge, synthetic pending credential metadata, secret, and otpauth URI for first-code activation. The user and stored credential are created when activation succeeds.

Request Body required

Section titled “Request Body required ”
Media type application/json
object
email
required
string format: email
name
string
label
string
<= 100 characters
custom_fields
object
key
additional properties
human_verification_response
string
cf_turnstile_response
string
authorization_challenge_id
string
invite_token

Tenant invitation token. Checked, and one use reserved for this signup, before the options are returned; applied to the account activation creates.

string
>= 1 characters
invitation_email_proof

Proof of the invited email from /api/v1/invitations/email-verification/verify, needed when the tenant requires the email an invitation names to be proved.

string
key
additional properties
Example 
{
  "email": "user@example.com",
  "name": "Example User",
  "label": "Authenticator app",
  "custom_fields": {}
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

TOTP signup enrollment options response.

Media type application/json
object
challenge_id
required
string
expires_in
required
integer
credential
required
object
id
required
string
label
required
string
algorithm
required
string
Allowed values: SHA1 SHA256 SHA512
digits
required
integer
Allowed values: 6 8
period
required
integer
window
required
integer
status
required
string
Allowed values: pending active disabled
created_at
required
integer format: int64
activated_at
integer | null format: int64
last_used_at
integer | null format: int64
secret
required

Base32 TOTP secret shown once during enrollment.

string
otpauth_uri
required
string format: uri
profile
required
object
algorithm
required
string
digits
required
integer
period
required
integer
window
required
integer
Example 
{
  "credential": {
    "algorithm": "SHA1",
    "digits": 6,
    "status": "pending"
  }
}

400

Section titled “400 ”

Error response.

Media type application/json
object
error
string
error_description
string
message
string
webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object
unknown_credential
boolean
key
additional properties
Example generated
{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}