Authentication Guide
Rich Utilities uses the Authentication service for centralized identity management. Learn how to authenticate your requests using JWT tokens for user sessions or API keys for server-to-server integrations.
Overview
The Rich Utilities platform supports two authentication methods:
- JWT Tokens: Short-lived tokens for user sessions (15-minute access tokens with 7-day refresh tokens)
- API Keys: Long-lived keys for server-to-server integrations (v1 simple keys or v2 scoped keys)
All API requests must include an authentication header. Unauthenticated requests will receive a 401 Unauthorized response.
JWT Authentication
JWT (JSON Web Token) authentication is the recommended approach for user-facing applications.
Token Types
| Token | Lifetime | Purpose |
|---|---|---|
| Access Token | 15 minutes | API requests |
| Refresh Token | 7 days | Obtain new access tokens |
Authentication Flow
- Register a new user account via
/auth/register - Login to receive a token pair via
/auth/login - Use the access token in the
Authorizationheader - Refresh when the access token expires via
/auth/refresh - Logout to revoke tokens via
/auth/logout
Example Usage
Token Refresh
When your access token expires (after 15 minutes), use the refresh token to get a new pair:
Store refresh tokens securely. They are long-lived and can be used to obtain new access tokens.
API Keys
API keys are best for server-to-server integrations, background jobs, and MCP server configurations.
v1 API Keys (Legacy)
Simple hashed keys suitable for basic integrations:
API keys are shown only once during generation. Store them securely in environment variables. If lost, you must generate a new key.
Scoped API Keys
v2 API keys provide granular permissions using bitfield scopes.
Key Format
v2 keys follow the format: ru_v2_<12_char_prefix>_<32_char_secret> (51 characters total)
Example: ru_v2_abcd1234efgh_0123456789abcdef0123456789abcdef
Available Scopes
| Resource | Actions |
|---|---|
companies | read, write, delete, admin |
leads | read, write, delete, admin |
contacts | read, write, delete, admin |
enrichment | read, write, delete, admin |
search | read |
admin | read, write, delete, admin |
Scope format: {resource}:{action}
Example scopes: ["companies:read", "leads:write", "contacts:read"]
Creating Scoped Keys
Using Scoped Keys
Checking Scopes
You can check what scopes an API key has:
Security Best Practices
Storing Credentials
Environment Variables:
macOS Keychain:
Docker Secrets:
Rate Limiting
The API enforces rate limits:
| Endpoint Type | Limit |
|---|---|
| Authentication | 5 attempts per minute |
| General API | 60 requests per minute (default) |
| Scoped Keys | Configurable per key (default: 1000 RPM) |
Rate limit headers are included in responses:
X-RateLimit-Limit: Request limitX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Reset timestamp
Failed Authentication
After 5 failed login attempts, accounts are locked for 15 minutes. Contact support if you need immediate assistance.
Token Expiration
| Token Type | Expiration | Refreshable? |
|---|---|---|
| Access Token | 15 minutes | Yes (with refresh token) |
| Refresh Token | 7 days | No (login again) |
| API Key v1 | Never (until revoked) | N/A |
| API Key v2 | Configurable | N/A |
Revoking Access
Revoke JWT Tokens:
Revoke API Keys:
Password Security
Rich Utilities uses Argon2id for password hashing with the following parameters:
- Memory: 64 MB
- Iterations: 3
- Parallelism: 4 threads
This provides post-quantum resistance against password cracking attempts.
HTTPS Only
All authentication endpoints require HTTPS. HTTP requests are automatically redirected to HTTPS in production.
SDK Authentication
Official SDKs handle authentication automatically:
Error Reference
| Status | Error | Description |
|---|---|---|
| 401 | unauthorized | Missing or invalid credentials |
| 401 | invalid_credentials | Wrong email/password |
| 401 | token_expired | JWT token has expired |
| 403 | forbidden | Valid credentials but insufficient permissions |
| 403 | admin_access_required | Endpoint requires admin role |
| 429 | rate_limit_exceeded | Too many requests |
| 423 | account_locked | Too many failed login attempts |
For complete API reference, see the Authentication API documentation.