Authentication Methods
ActumX supports two authentication methods depending on the use case:
- Session-based authentication - For dashboard UI requests
- API key authentication - For programmatic API access
Session-Based Authentication
The dashboard uses better-auth for session management with email and password authentication.
Session Details
- Sessions are managed via secure HTTP-only cookies
- Session TTL: 30 days
- Base path:
/auth/api
- Cross-subdomain cookies enabled in production (
.actumx.app)
Login
Login is handled through the better-auth endpoints at /auth/api. Sessions are automatically maintained via cookies.
curl -X POST https://api.actumx.app/auth/api/sign-in \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "your-password"
}'
API Key Authentication
API keys are used for programmatic access to the ActumX API. They can be created through the dashboard.
Using API Keys
API keys can be passed in two ways:
curl https://api.actumx.app/v1/agents \
-H "x-api-key: actumx_live_abc123..."
curl https://api.actumx.app/v1/agents \
-H "Authorization: Bearer actumx_live_abc123..."
actumx_live_[random_string]
Security Best Practices
API keys provide full access to your account. Keep them secure and never commit them to version control.
- Store API keys in environment variables
- Use separate API keys for different applications
- Rotate keys regularly
- Revoke unused keys immediately
- The full API key is only shown once at creation
For endpoints that require payment (HTTP 402), you’ll need to include additional headers after settlement:
x-payment-id - The payment ID from the 402 responsex-payment-proof - The receipt ID returned from the settlement endpoint
See the x402 endpoints documentation for detailed payment flow.
curl https://api.actumx.app/v1/protected/quote \
-H "x-api-key: actumx_live_abc123..." \
-H "x-payment-id: x402tx_xyz789" \
-H "x-payment-proof: receipt_def456"
Protected Endpoints
Most endpoints require authentication. Unauthenticated requests will receive a 401 status:
{
"error": "unauthorized"
}
{
"error": "missing_or_invalid_api_key"
}
Next Steps