Auth Apps API reference — Cliodot Documentation

Error codes your integration may encounter on /auth endpoints:

Code	HTTP	Meaning
`AUTH_APP_NOT_FOUND`	404	Auth app missing, wrong tenant, or inactive app reference
`AUTH_APP_DISABLED`	403	Auth app status is `disabled`
`AUTH_UNAUTHORIZED_APP`	401 / 403	Missing, invalid, or mismatched runtime credentials
`AUTH_USER_NOT_FOUND`	404	No user record for the given `external_user_id`
`AUTH_ENROLLMENT_NOT_FOUND`	404	No enrollment exists for the requested factor
`AUTH_ENROLLMENT_ALREADY_ACTIVE`	409	Factor already enrolled and active
`AUTH_ENROLLMENT_PENDING`	409	Enrollment exists but is not in pending confirmation state
`AUTH_ENROLLMENT_EXPIRED`	410	Pending enrollment window expired; re-enroll required
`AUTH_INVALID_CODE`	400	TOTP or OTP code did not match
`AUTH_REPLAY_DETECTED`	409	TOTP code already used within the replay window
`AUTH_USER_LOCKED`	423	Too many failed verifications; user temporarily locked
`AUTH_MFA_NOT_ENABLED`	404	User has no active MFA enrollment
`AUTH_MFA_ALREADY_ENABLED`	409	MFA is already active for the requested operation
`AUTH_RECOVERY_CODE_INVALID`	400	Recovery code not found or malformed
`AUTH_RECOVERY_CODE_USED`	409	Recovery code was already consumed
`AUTH_RATE_LIMITED`	429	Per-IP rate limit exceeded
`AUTH_RESEND_COOLDOWN`	429	Resend rejected (`resend_mode: reject`); includes `retry_after_seconds`
`AUTH_RESEND_QUEUE_FULL`	429	Resend queue at capacity (`resend_mode: queue`)
`AUTH_OTP_EXPIRED`	410	OTP challenge expired
`AUTH_DESTINATION_REQUIRED`	422	Email or phone missing for OTP/magic-link delivery
`AUTH_DELIVERY_FAILED`	422 / 502	Delivery not configured, connector missing, or send failed
`AUTH_METHOD_NOT_ENABLED`	422	Factor not enabled on the auth app
`AUTH_INVALID_PROVIDER`	400	Provider path param is not `email_otp` or `sms_otp`
`AUTH_MAGIC_LINK_INVALID`	400	Token malformed, unknown, or challenge not found
`AUTH_MAGIC_LINK_EXPIRED`	400	Magic link challenge past TTL
`AUTH_MAGIC_LINK_ALREADY_USED`	400	Magic link token already consumed

Upsert User


Method	`PUT`
Path	`/auth/apps/:appId/users/:externalUserId`
Auth	`aak_` API key or App ID + secret
Description	Upsert user metadata before or during MFA enrollment.

Request body (all optional)

Field	Type
`email`	string
`phone`	string
`phone_country_code`	string
`display_name`	string
`metadata`	object

Sample success response 200

{
 "ok": true,
 "user": {
   "_id": "auth_user_507f1f77bcf86cd799439012",
   "tenant_id": "tenant_456",
   "auth_app_id": "auth_app_507f1f77bcf86cd799439011",
   "external_user_id": "user_123",
   "email": "user@example.com",
   "display_name": "Jane Doe",
   "metadata": { "department": "engineering" },
   "created_at": "2026-07-09T10:30:00.000Z",
   "updated_at": "2026-07-09T10:30:00.000Z"
 }
}

Common errors: 401 AUTH_UNAUTHORIZED_APP, 403 AUTH_APP_DISABLED, 429 AUTH_RATE_LIMITED

cURL

curl -X PUT "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123" \
 -H "Authorization: Bearer YOUR_APP_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"email": "user@example.com", "display_name": "Jane Doe", "metadata": {"department": "engineering"}}'

MFA Status#

Get MFA Status


Method	`GET`
Path	`/auth/apps/:appId/users/:externalUserId/mfa/status`
Auth	App credentials
Description	Get MFA enrollment status for a user across all factors.

Sample success response 200

{
 "ok": true,
 "external_user_id": "user_123",
 "mfa_enabled": true,
 "factors": [
   {
     "factor_type": "totp",
     "status": "active",
     "activated_at": "2026-07-09T10:45:00.000Z",
     "recovery_codes_remaining": 8
   }
 ]
}

Common errors: 401 AUTH_UNAUTHORIZED_APP, 429 AUTH_RATE_LIMITED

cURL

curl "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/status" \
 -H "Authorization: Bearer YOUR_APP_API_KEY"