Finish TOTP Enrollment

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

Confirms an authenticator app with its current code. Call it after Begin TOTP enrollment. When this call succeeds, two-factor authentication is on.

Operation Type (for Signing)

Header Field	Type	Content
`"type"`	string	`"finish_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`
`”enrollment_id”`	string	required	Enrollment ID (UUID) from Begin TOTP enrollment	`8f14e45f-ceea-467a-9575-0b3a8d6c3f1e`
`”code”`	string	required	The authenticator app’s current code. Exactly 6 digits. Not part of the signed payload	`123456`
`”expiry_window”`	integer	optional	Signature expiry in milliseconds	`30000`

{
  "account": "42trU9A5...",
  "signature": "5j1Vy9Uq...",
  "timestamp": 1716200000000,
  "enrollment_id": "8f14e45f-ceea-467a-9575-0b3a8d6c3f1e",
  "code": "123456",
  "expiry_window": 30000
}

Sign this request with the account’s own key. Agent wallets cannot sign it. The account must be a main account. This call needs no proof. Begin TOTP enrollment already checked it.

If the code is wrong, the enrollment stays open. Try again.
After 5 wrong codes, the enrollment ends. Start again.
After 10 minutes, the enrollment expires. Start again.

The code that you send is used up. Wait for the next code before you send your first proof.

Signing

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

{"data":{"enrollment_id":"8f14e45f-ceea-467a-9575-0b3a8d6c3f1e"},"expiry_window":30000,"timestamp":1716200000000,"type":"finish_totp_enrollment"}

Response

Status 200: Authenticator app added

{
  "success": true,
  "data": {
    "recovery_keys": [
      "3f9a-1c0b-77de-a4e2-0b19-5c6d-e8f0-2a7b",
      "9e2d-4b7a-0c61-f385-a7d2-6e19-3b40-c8f5",
      "..."
    ]
  },
  "error": null,
  "code": null
}

Field	Type	Description
`'recovery_keys'`	array	New recovery keys. 10 keys for your first factor. Empty when 2FA was already on

Pacifica shows recovery keys only once. Store them somewhere safe.

Status 400: Invalid request parameters or signature
Status 401: The code is wrong, or the enrollment is unknown, expired, or ended

{
  "success": false,
  "data": null,
  "error": "two-factor proof is invalid or has expired",
  "code": 401,
  "error_id": "second_factor_invalid"
}

Status 403: The account is a subaccount, or it does not exist
Status 422: A factor change ended this enrollment (two-factor settings changed. Start again.), or the account has no room for another factor
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,
    "enrollment_id": "8f14e45f-ceea-467a-9575-0b3a8d6c3f1e",
    "code": "123456"
}

response = requests.post(
    "/api/v1/account/2fa/totp/finish",
    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)