Begin TOTP Enrollment

POST /api/v1/account/2fa/totp/begin

Starts adding an authenticator app as a two-factor factor. The response has a new TOTP secret. Add it to an authenticator app, then call Finish TOTP enrollment with a code within 10 minutes.

Operation Type (for Signing)

Header Field	Type	Content
`"type"`	string	`"begin_totp_enrollment"`

Request Body

Field	Type	Need	Description	Example
`”account”`	string	required	User’s wallet address	`42trU9A5…`
`“signature”`	string	required	Cryptographic signature	`5j1Vy9Uq…`
`“timestamp”`	integer	required	Current timestamp in milliseconds	`1716200000000`
`”label”`	string	required	Your name for the factor. 1 to 64 characters, with no control characters and no leading or trailing spaces	`Authenticator app`
`”expiry_window”`	integer	optional	Signature expiry in milliseconds	`30000`
`”two_factor”`	object	conditional	Proof. Required while 2FA is on. Not part of the signed payload. See Proofs

{
  "account": "42trU9A5...",
  "signature": "5j1Vy9Uq...",
  "timestamp": 1716200000000,
  "label": "Authenticator app",
  "expiry_window": 30000
}

Sign this request with the account’s own key. Agent wallets cannot sign it. The account must be a main account. If 2FA is already on, send a proof in two_factor. Any proof type works, including a recovery key. After the proof passes, you can send the same request with the same label again for 5 minutes without a new proof. An account has one authenticator app. If it already has one, the new one replaces it when you finish enrollment.

Signing

Sign label as the data object. Do not sign two_factor. For the request above, the message to sign is:

{"data":{"label":"Authenticator app"},"expiry_window":30000,"timestamp":1716200000000,"type":"begin_totp_enrollment"}

Response

Status 200: Enrollment started

{
  "success": true,
  "data": {
    "enrollment_id": "8f14e45f-ceea-467a-9575-0b3a8d6c3f1e",
    "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
    "otpauth_uri": "otpauth://totp/Pacifica:42trU9...xNc6?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=Pacifica"
  },
  "error": null,
  "code": null
}

Field	Type	Description
`'enrollment_id'`	string	Enrollment ID (UUID). Send it to Finish TOTP enrollment within 10 minutes
`'secret'`	string	TOTP secret in base32. Type it into an authenticator app if you cannot scan a QR code
`'otpauth_uri'`	string	`otpauth://` URI with the secret. Show it as a QR code for an authenticator app

Codes use SHA-1, 6 digits, and a 30-second period. The authenticator app shows the issuer Pacifica and a short form of your wallet address. Keep the secret private. Anyone who has it can make codes.

Status 400: Invalid request parameters, label, or signature
Status 401: The proof is wrong, expired, or already used
Status 403: The account is a subaccount, or it does not exist
Status 422: The account has no room for another factor (a user can have at most 8 factors)
Status 428: 2FA is on, and the request has no two_factor

{
  "success": false,
  "data": null,
  "error": "two-factor proof is required",
  "code": 428,
  "error_id": "second_factor_required"
}

Status 429: Too many proof attempts, or more than 20 enrollments started in 10 minutes
Status 500: Internal server error
Status 503: The two-factor service is unavailable. Retry later

Code Example (Python)

import requests

payload = {
    "account": "42trU9A5...",
    "signature": "5j1Vy9Uq...",
    "timestamp": 1716200000000,
    "label": "Authenticator app"
}

response = requests.post(
    "/api/v1/account/2fa/totp/begin",
    json=payload,
    headers={"Content-Type": "application/json"}
)

data = response.json()

​Operation Type (for Signing)

​Request Body

​Signing

​Response

​Code Example (Python)

Operation Type (for Signing)

Request Body

Signing

Response

Code Example (Python)