API Reference

Verify TOTP code

POST /api/auth/verify-totp

Completes login by verifying the TOTP code. Sets the authenticated browser session on success.

Operation IDverifyTotp

Authentication

No authentication is required.

Request body

This request body is required.

Content typeapplication/json

requestobject

1 property

codestringrequired

Success response body

200TOTP verified, session established

TOTP verified, session established

Content typeapplication/json

responseobject

1 property

successboolean

Error responses

400Missing pending browser session or TOTP code. Messages distinguish the two cases so the client can recover (re-login vs re-enter code).

Missing pending browser session or TOTP code. Messages distinguish the two cases so the client can recover (re-login vs re-enter code).

No response content schema is documented.

401Not authenticated

Not authenticated

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

{
  "error": "AUTH_ERROR",
  "message": "Not authenticated"
}

429Too many requests

Too many requests

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

{
  "error": "RATE_LIMITED",
  "message": "Too many failed TOTP attempts. Try again later."
}

Code examples

curl --request POST \
  --url 'https://your-envoy.example.com/api/auth/verify-totp' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "string"
}'

const response = await fetch("https://your-envoy.example.com/api/auth/verify-totp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "code": "string"
  }),
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);