Auth Apps overview

Session ownership: Auth Apps verifies MFA factors. Your backend remains responsible for primary authentication and for issuing sessions or JWTs.

Cliodot Auth Apps let you add multi-factor authentication to any application without building TOTP, OTP delivery, or magic-link infrastructure yourself.

Your application backend calls the Auth Apps API server-to-server to enroll users, send OTPs and magic links, and verify codes.

external_user_id is your user identifier — not a Cliodot platform user ID.

Secrets shown once at generation:

Base URL#

Prepend your Cliodot API host (e.g. https://api.example.com).

Example: Verify TOTP → POST https://api.example.com/auth/apps/{appId}/users/{externalUserId}/mfa/totp/verify

Authentication#

All endpoints except public magic-link verify require one of the following credential pairs. Requests are rate-limited to 30 requests/minute per IP + path + app + user.

Option A — API key (recommended)

Authorization: Bearer aak_<app_api_key>

Option B — App ID + secret

X-Cliodot-App-Id: auth_app_507f1f77bcf86cd799439011
X-Cliodot-App-Secret: YOUR_APP_SECRET

Runtime requests must target the same appId in the URL path as the authenticated credentials. Mismatched appId returns 403 with AUTH_UNAUTHORIZED_APP.

The public magic-link verify endpoint (POST /auth/apps/:appId/magic-link/verify) requires no authentication — only the token in the request body. It is rate-limited to 15 requests/minute per IP.

Response Envelope#

Success#

{
 "ok": true
}

Additional fields are merged at the top level (e.g. user, verified, factors).

Error#

{
 "ok": false,
 "error": "Human-readable message",
 "code": "AUTH_ERROR_CODE"
}

Some errors include extra fields (e.g. retry_after_seconds on AUTH_RESEND_COOLDOWN).

Validation failures from Express validators may return 400 without a code field.

Your backend owns authentication. Auth Apps handles MFA only.

TOTP enrollment#

1. PUT /auth/apps/:appId/users/:externalUserId — upsert user metadata (optional)
2. POST .../mfa/totp/enroll — receive secret, otpauth_url, qr_code_data_url
3. Display QR code to the end user
4. POST .../mfa/totp/confirm — submit first 6-digit code to activate
5. POST .../mfa/recovery-codes — optionally generate backup codes (shown once)

TOTP login verification#

1. Your backend validates the user's password (your auth system)
2. POST .../mfa/totp/verify with the TOTP code — or POST .../mfa/recovery-codes/verify
3. If verified: true, issue your own session/JWT

Email/SMS OTP#

1. Configure delivery templates, message templates, and enabled methods in the Cliodot portal
2. POST .../providers/{email_otp|sms_otp}/enroll — enroll and send first code
3. POST .../providers/{email_otp|sms_otp}/verify — verify code at login
4. Use challenge or resend to issue new codes

Magic Link#

1. Configure magic_link_policy, delivery templates, and content in the Cliodot portal
2. POST .../providers/magic_link/enroll — send first link
3. End user clicks link; your app calls verify with the token (S2S or public endpoint)
4. On success, issue your own session

Default policies (overridable per app in the portal):