Skip to main content

Step-up authentication

Some endpoints require an extra X-Confirm-Token on top of your PAT — specifically, anything that's destructive (:cancel, :rebuild, :restore, :transfer) or billed (:pay, :accept, account password changes). This is our equivalent of "type your password again to confirm".

Getting a token​

curl -X POST https://api.vps-server.host/v1/auth/step-up \
  -H "Authorization: Bearer $PAT" \
  -d '{"method":"password","password":"…"}'
{
  "token":      "cft_1QH9Z2bC3dE4fG5hI6jK7lM8nO9pQ",
  "expires_at": "2026-05-21T14:35:00Z"
}

If your account has 2FA enabled:

curl -X POST https://api.vps-server.host/v1/auth/step-up \
  -H "Authorization: Bearer $PAT" \
  -d '{"method":"totp","code":"123456"}'

Using a token​

Attach it as a header on the protected request:

curl -X POST https://api.vps-server.host/v1/invoices/inv_42:pay \
  -H "Authorization: Bearer $PAT" \
  -H "X-Confirm-Token: cft_1QH9Z2bC3dE4fG5hI6jK7lM8nO9pQ" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"method":"pm_default"}'

TTL​

5 minutes from issuance. Get a new one — you can keep one in memory in a CI job, but always re-fetch if more than 4 minutes have passed.

CLI helper​

vpsctl auth step-up   # prompts for password/code, caches the token in your keychain

The CLI auto-injects the cached X-Confirm-Token on protected calls.