Core documentation content is fully readable without JavaScript. The table of contents, assistant, and some copy buttons enhance the experience but are not required.

API & Keys

Authentication & Account Security

Zephex uses three authentication layers: Supabase Auth for dashboard and CLI setup login, Auth0 for MCP connector OAuth (Claude.ai, ChatGPT), and API key Bearer tokens for MCP tool calls. This page covers all three, plus MFA, sessions, and hardening.

Authentication Flow

Every tool call carries the same Bearer token. The proxy validates it before any tool executes.

API KEY AUTHENTICATION

Every MCP tool call requires a valid API key in the Authorization header:

Authorization: Bearer mcp_prod_cosmic-1861.a7f3b9c2d1e4...

How API key validation works

The proxy extracts the Bearer token from the Authorization header.
The token is HMAC-SHA256 hashed with a per-key salt and compared against stored hashes in the database.
If a match is found, the key's user, tier, scope, and status are loaded.
Revoked keys, expired keys, and keys exceeding their per-key cap are rejected.
The request proceeds to rate-limit checks and then tool execution.

Plaintext API keys are shown exactly once at creation time. They are never stored, logged, or retrievable after that moment.

API KEY FORMATS

Format	Example prefix	Notes
Legacy	mcp_sk_88d32efe...	Older keys, still valid
Current	mcp_prod_cosmic-1861.a7f3...	Environment-tagged, human-readable prefix

The prefix (before the dot) is stored in plaintext for display purposes. The secret (after the dot) is hashed. You can identify which key made a request by its prefix without exposing the secret.

DASHBOARD AUTHENTICATION

Email + password — passwords are hashed with bcrypt (cost factor 10). Minimum 12 characters with complexity rules (see signup).
OAuth providers — GitHub and Google OAuth 2.0. No password stored for OAuth-only accounts.
Magic link — passwordless login via email link (expires in 10 minutes).
Password reset — secure token sent to registered email, expires in 1 hour.

OAUTH 2.1 FOR CLI TOOLS

CLI-based MCP clients (Claude Code, Kiro CLI, Gemini CLI) can authenticate using OAuth 2.1 with PKCE. This avoids storing long-lived API keys on disk.

1. Client requests authorization   GET https://zephex.dev/oauth/authorize     ?response_type=code     &client_id=YOUR_CLIENT_ID     &redirect_uri=https://YOUR_APP/callback     &code_challenge=BASE64URL(SHA256(verifier))     &code_challenge_method=S256     &resource=https://zephex.dev/mcp 2. User authenticates (Auth0 — MCP connector clients) 3. Callback receives authorization code   GET /callback?code=AUTH_CODE 4. Client exchanges code for token   POST https://zephex.dev/oauth/token     grant_type=authorization_code     &code=AUTH_CODE     &code_verifier=ORIGINAL_VERIFIER     &redirect_uri=https://YOUR_APP/callback

Access tokens expire after 1 hour.
Refresh tokens expire after 7 days and rotate on each use.
PKCE (S256) is mandatory — plain code challenges are rejected.
Discovery endpoint: /.well-known/oauth-authorization-server

MULTI-FACTOR AUTHENTICATION (MFA)

TOTP-based MFA (compatible with Google Authenticator, Authy, 1Password, etc.).
Enable from Dashboard → Settings → Security.
Backup codes generated at setup (one-time use, store securely).
MFA is verified on every login and on sensitive actions (password change, key creation).
MFA secrets are encrypted with AES-256-GCM before database storage.

SESSION MANAGEMENT

Sessions use HttpOnly, Secure, SameSite=Strict cookies.
Session tokens are rotated on privilege escalation (password change, MFA enable).
Maximum 5 concurrent sessions per account (configurable).
Idle timeout: 7 days. Absolute timeout: 30 days.
Sessions are invalidated on password change and account lockout.
CSRF protection on all state-changing requests (double-submit cookie pattern).

ACCOUNT LOCKOUT

Failed attempts	Action	Duration
5 in 15 minutes	Account locked	15 minutes
10 in 1 hour	Account locked	1 hour
20 in 24 hours	Account locked + email alert	24 hours

Lockout applies to the account, not the IP. This prevents credential stuffing while allowing legitimate users on shared networks. A security alert email is sent on the third lockout tier.

IP-BASED RATE LIMITING

Authentication endpoints: 10 attempts per IP per minute.
API key validation: 1,000 requests per IP per minute (covers multiple users behind NAT).
Signup: 3 accounts per IP per hour (prevents mass account creation).
Password reset: 5 requests per IP per hour.

SECURITY BEST PRACTICES

Enable MFA — protects your account even if your password is compromised.
Use environment-specific keys — create separate keys for dev, staging, and production.
Set per-key caps — limit each key's monthly requests to contain blast radius.
Rotate keys regularly — set a rotation schedule (Dashboard → API Keys → Rotate).
Use tool scopes — restrict keys to only the tools they need (Pro/Max).
Revoke unused keys — delete keys you no longer use.
Monitor usage — check Dashboard → Usage for unexpected spikes.
Enable notifications — get alerted at 50%, 75%, 90% usage thresholds.

DISPOSABLE EMAIL BLOCKING

Signup with disposable/temporary email providers (mailinator, guerrillamail, etc.) is blocked. This prevents abuse of the free tier through mass account creation. If your legitimate email domain is incorrectly blocked, contact support@zephex.dev.

REPORT A VULNERABILITY

Found a security issue? Email support@zephex.dev with reproduction steps. We respond within 48 hours and do not pursue legal action against good-faith security researchers.

API & Keys

Authentication & Account Security

Authentication Flow

Every tool call carries the same Bearer token. The proxy validates it before any tool executes.

API KEY AUTHENTICATION

Every MCP tool call requires a valid API key in the Authorization header:

Authorization: Bearer mcp_prod_cosmic-1861.a7f3b9c2d1e4...

How API key validation works

The proxy extracts the Bearer token from the Authorization header.
The token is HMAC-SHA256 hashed with a per-key salt and compared against stored hashes in the database.
If a match is found, the key's user, tier, scope, and status are loaded.
Revoked keys, expired keys, and keys exceeding their per-key cap are rejected.
The request proceeds to rate-limit checks and then tool execution.

Plaintext API keys are shown exactly once at creation time. They are never stored, logged, or retrievable after that moment.

API KEY FORMATS

Format	Example prefix	Notes
Legacy	mcp_sk_88d32efe...	Older keys, still valid
Current	mcp_prod_cosmic-1861.a7f3...	Environment-tagged, human-readable prefix

The prefix (before the dot) is stored in plaintext for display purposes. The secret (after the dot) is hashed. You can identify which key made a request by its prefix without exposing the secret.

DASHBOARD AUTHENTICATION

Email + password — passwords are hashed with bcrypt (cost factor 10). Minimum 12 characters with complexity rules (see signup).
OAuth providers — GitHub and Google OAuth 2.0. No password stored for OAuth-only accounts.
Magic link — passwordless login via email link (expires in 10 minutes).
Password reset — secure token sent to registered email, expires in 1 hour.

OAUTH 2.1 FOR CLI TOOLS

CLI-based MCP clients (Claude Code, Kiro CLI, Gemini CLI) can authenticate using OAuth 2.1 with PKCE. This avoids storing long-lived API keys on disk.

1. Client requests authorization   GET https://zephex.dev/oauth/authorize     ?response_type=code     &client_id=YOUR_CLIENT_ID     &redirect_uri=https://YOUR_APP/callback     &code_challenge=BASE64URL(SHA256(verifier))     &code_challenge_method=S256     &resource=https://zephex.dev/mcp 2. User authenticates (Auth0 — MCP connector clients) 3. Callback receives authorization code   GET /callback?code=AUTH_CODE 4. Client exchanges code for token   POST https://zephex.dev/oauth/token     grant_type=authorization_code     &code=AUTH_CODE     &code_verifier=ORIGINAL_VERIFIER     &redirect_uri=https://YOUR_APP/callback

Access tokens expire after 1 hour.
Refresh tokens expire after 7 days and rotate on each use.
PKCE (S256) is mandatory — plain code challenges are rejected.
Discovery endpoint: /.well-known/oauth-authorization-server

MULTI-FACTOR AUTHENTICATION (MFA)

TOTP-based MFA (compatible with Google Authenticator, Authy, 1Password, etc.).
Enable from Dashboard → Settings → Security.
Backup codes generated at setup (one-time use, store securely).
MFA is verified on every login and on sensitive actions (password change, key creation).
MFA secrets are encrypted with AES-256-GCM before database storage.

SESSION MANAGEMENT

Sessions use HttpOnly, Secure, SameSite=Strict cookies.
Session tokens are rotated on privilege escalation (password change, MFA enable).
Maximum 5 concurrent sessions per account (configurable).
Idle timeout: 7 days. Absolute timeout: 30 days.
Sessions are invalidated on password change and account lockout.
CSRF protection on all state-changing requests (double-submit cookie pattern).

ACCOUNT LOCKOUT

Failed attempts	Action	Duration
5 in 15 minutes	Account locked	15 minutes
10 in 1 hour	Account locked	1 hour
20 in 24 hours	Account locked + email alert	24 hours

Lockout applies to the account, not the IP. This prevents credential stuffing while allowing legitimate users on shared networks. A security alert email is sent on the third lockout tier.

IP-BASED RATE LIMITING

Authentication endpoints: 10 attempts per IP per minute.
API key validation: 1,000 requests per IP per minute (covers multiple users behind NAT).
Signup: 3 accounts per IP per hour (prevents mass account creation).
Password reset: 5 requests per IP per hour.

SECURITY BEST PRACTICES

Enable MFA — protects your account even if your password is compromised.
Use environment-specific keys — create separate keys for dev, staging, and production.
Set per-key caps — limit each key's monthly requests to contain blast radius.
Rotate keys regularly — set a rotation schedule (Dashboard → API Keys → Rotate).
Use tool scopes — restrict keys to only the tools they need (Pro/Max).
Revoke unused keys — delete keys you no longer use.
Monitor usage — check Dashboard → Usage for unexpected spikes.
Enable notifications — get alerted at 50%, 75%, 90% usage thresholds.

DISPOSABLE EMAIL BLOCKING

REPORT A VULNERABILITY

Found a security issue? Email support@zephex.dev with reproduction steps. We respond within 48 hours and do not pursue legal action against good-faith security researchers.

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Authentication & Account Security

How API key validation works

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Authentication & Account Security

How API key validation works