Authentication

API Keys

The Turen API uses API keys for authentication. Include your key in the X-API-Key header with every request:

curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/registered-agents

API keys use the prefix sk_live_ and are scoped to a single organization. All data returned is filtered to your organization.

Creating an API Key

Log in to the Turen dashboard
Go to Org Settings > API Keys
Click Create API Key
Copy the key immediately: it’s only shown once

Key Types

Turen uses three credential types. Only API keys are used for the dashboard API:

Type	Prefix	Usage
API Key	`sk_live_`	Dashboard API access (this documentation)
Registration Key	`rk_live_`	Agent registration (not used for API)
Agent Secret	`as_live_`	Agent-to-platform communication (not used for API)

Security Best Practices

Store keys in environment variables or a secrets manager, never in source code
Use one key per integration so you can revoke individually
Rotate keys regularly: create a new key, update your integration, then revoke the old one
Monitor key usage in Org Settings > API Keys (last-used timestamps)
Revoke unused keys promptly

Multi-Factor Authentication (MFA)

Turen accounts can add a TOTP (authenticator app) second factor. MFA applies to user sign-in (dashboard and desktop app), not to sk_live_ API keys, so these endpoints authenticate with a user session’s Supabase access token in the Authorization: Bearer header rather than the X-API-Key header.

You enroll and manage MFA factors in the dashboard under User Settings. The endpoints below are the ones the dashboard and desktop app call. Once a factor is enrolled, the desktop app prompts for the 6-digit code during sign-in (email/password and Google sign-in both support it).

All MFA endpoints are under /api/v1/auth/supabase/mfa and require a Bearer token:

Method	Path	Description
POST	`/auth/supabase/mfa/enroll`	Start TOTP enrollment. Returns a QR code, secret, and provisioning URI
POST	`/auth/supabase/mfa/challenge`	Create a challenge for a factor. Body: `{ "factor_id": "..." }`
POST	`/auth/supabase/mfa/verify`	Verify a 6-digit code to finish enrollment or complete sign-in. Body: `{ "factor_id": "...", "challenge_id": "...", "code": "123456" }`
GET	`/auth/supabase/mfa/factors`	List the current user’s enrolled factors
DELETE	`/auth/supabase/mfa/{factor_id}`	Remove (unenroll) a factor

Enrollment returns the data you need to add the factor to an authenticator app, then you confirm it with a challenge plus a verify:

curl -X POST https://api.prod.turen.io/api/v1/auth/supabase/mfa/enroll \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"friendly_name":"Authenticator App"}'

{
  "id": "factor-uuid",
  "type": "totp",
  "qr_code": "data:image/svg+xml;base64,...",
  "secret": "BASE32SECRET",
  "uri": "otpauth://totp/..."
}

Sign-in with MFA: when an account has a verified factor, sign-in returns a session at assurance level aal1 (password only) and indicates a second factor is needed. Create a challenge for the factor, then verify the 6-digit code to upgrade to a fully authenticated (aal2) session:

# 1. Create a challenge for the enrolled factor
curl -X POST https://api.prod.turen.io/api/v1/auth/supabase/mfa/challenge \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"factor_id":"factor-uuid"}'

# 2. Verify the code from the authenticator app
curl -X POST https://api.prod.turen.io/api/v1/auth/supabase/mfa/verify \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"factor_id":"factor-uuid","challenge_id":"challenge-uuid","code":"123456"}'

Health Check

The health endpoint does not require authentication:

curl https://api.prod.turen.io/api/v1/health

{
  "status": "ok",
  "timestamp": "2026-02-17T10:30:00Z",
  "version": "0.1.0",
  "database": "connected"
}

​API Keys

​Creating an API Key

​Key Types

​Security Best Practices

​Multi-Factor Authentication (MFA)

​Health Check

API Keys

Creating an API Key

Key Types

Security Best Practices

Multi-Factor Authentication (MFA)

Health Check