Authentication

API keys, JWT tokens, session management, and security best practices.

Authentication Methods

RadMah AI supports two authentication methods for the Client API:

Method	Header	Use Case
API Key	`X-API-Key: sl_live_...`	SDK, CLI, CI/CD pipelines, server-to-server
JWT Bearer Token	`Authorization: Bearer <token>`	Web dashboard sessions, browser-based clients

API Keys

API keys are the recommended authentication method for programmatic access. Keys use the sl_live_ prefix followed by a 32-character hex suffix.

Creating an API Key

Navigate to Settings → API Keys in the client dashboard, or use the REST API:

Create API key

curl -X POST https://api.radmah.ai/v1/client/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{ "name": "CI Pipeline Key" }'

⚠Store Your Key Immediately

The full API key is returned only once at creation time. It is stored as a SHA-256 hash -- the plaintext is never persisted and cannot be retrieved later. Copy it immediately and store it securely.

Using an API Key

Authenticate with API key

from radmah_sdk import RadMahClient

client = RadMahClient(api_key="sl_live_abc123...")

Key Management

API keys are scoped to a tenant. You can create multiple keys with descriptive names and revoke them individually. Revoked keys are immediately invalid across all API calls.

JWT Sessions

JWT tokens are used for browser-based sessions in the client dashboard.

Token Type	TTL	Delivery
Access Token	15 minutes	Authorization header or HttpOnly cookie
Refresh Token	30 days	HttpOnly cookie

Login Flow

curl -X POST https://api.radmah.ai/v1/client/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "..."
  }'

Multi-Factor Authentication

MFA uses TOTP (RFC 6238) with 30-second windows and 6-digit codes. When MFA is enabled on an account, it is enforced at every login and cannot be bypassed.

Enroll via Settings → Security in the client dashboard
Backup codes are generated at enrollment and stored hashed
Compatible with any TOTP authenticator app (Google Authenticator, Authy, 1Password, etc.)
Every sign-in waits for the code: a login, an OAuth or SSO sign-in and an accepted invitation answer 202 with {"mfa_required": true, "mfa_token": ...} and no session; POST /v1/client/auth/mfa/verify with that mfa_token and the code opens it (the SDK keeps the token: login(), then mfa_verify(code))
Wrong codes count toward the account's lockout, as wrong passwords do; a locked account is refused (429 ACCOUNT_LOCKED) before a password or a code is checked
Sign-up never signs in an account that already exists: it answers 409 USER_EXISTS whatever password was sent, and checks none

SSO (Enterprise)

Enterprise and Sovereign plans support SAML 2.0 and OIDC single sign-on, configured per tenant. SSO is combined with SCIM 2.0 for automated user provisioning and deprovisioning. See SSO & SCIM for configuration details.

BYO API Key (LLM Providers)

✦Bring Your Own Key

Any plan can connect its own OpenAI, Azure OpenAI, Anthropic, Gemini or OpenAI-compatible API key via Settings → AI Providers, the SDK's update_llm_config(provider_type=..., api_key_ref=...) or rady ai-provider set --provider ... --key-stdin (the CLI reads the key from standard input, never from the command line). The key is stored encrypted and bound to your workspace: it is used for your workspace's AI calls only and is only ever shown masked. When configured, all AI calls route through the tenant's key and the monthly AI request cap is bypassed entirely.

Tenant Roles

Role	Capabilities
owner	Full tenant control; exactly one per tenant; transferable
admin	Manage members, billing and API keys (their own, and keys for members and viewers), invite members and viewers, run all jobs, manage datasets/seals, view usage
member	Run jobs, upload datasets, use chat assistant, view own results and own API keys; cannot manage members, API keys or billing (an owner or admin creates a key for them, acting with their role)
viewer	Read-only access to results, datasets, and evidence bundles; a key created for a viewer is read-only

Security Best Practices

ℹRecommendations

Use API keys for programmatic access, JWT for browser sessions
Rotate API keys periodically and revoke unused keys
Enable MFA for all user accounts, especially admins and owners
Store API keys in secret managers, never in source code
Use the minimum role required for each team member (principle of least privilege)
Review the API key list regularly and remove keys no longer in use