Rich Utilities

Authentication API

Centralized authentication and authorization service for the Rich Utilities platform. Manage users, issue JWT tokens, create scoped API keys, and administer the system.

Get StartedAPI Keys

Overview

The Authentication service provides:

  • User Management: Registration, login with Argon2id password hashing
  • JWT Tokens: Short-lived access tokens (15 min) + long-lived refresh tokens (7 days)
  • API Keys: Bitfield-scoped keys with granular permissions, rate limiting, and IP allowlists
  • Admin Operations: User management, audit logs, system stats
  • Security: Rate limiting, account lockout, suspicious activity tracking

Base URL

Authentication endpoints are available at:

Base URL

The Authentication service runs on port 8081 internally. Nginx routes /auth/* and /admin/* paths to this service.

Authentication

Register

Create a new user account. Passwords are hashed using Argon2id (post-quantum resistant).

Request Body

  • Name
    email
    Type
    string
    Description
    User email address (unique)
  • Name
    password
    Type
    string
    Description
    User password (min 8 characters)

Request

POST
/auth/register

Response (201)

Login

Authenticate and receive a token pair (access + refresh tokens).

Request Body

  • Name
    email
    Type
    string
    Description
    User email address
  • Name
    password
    Type
    string
    Description
    User password

Request

POST
/auth/login

Response (200)

Token Management

Refresh Token

Exchange a refresh token for a new token pair.

Request Body

  • Name
    refresh_token
    Type
    string
    Description
    The refresh token from login

Request

POST
/auth/refresh

Response (200)

Revoke Token

Revoke an access token before its natural expiration.

Headers: Authorization: Bearer <jwt>

Request Body

  • Name
    token
    Type
    string
    Description
    The access token to revoke

Request

POST
/auth/token/revoke

Response (200)

Logout

Log out the current user and revoke their token.

Headers: Authorization: Bearer <jwt>

Request

POST
/auth/logout

Response (200)

Validate Token

Validate a JWT token and get user information.

Request Body

  • Name
    token
    Type
    string
    Description
    The JWT token to validate

Request

POST
/auth/validate-token

Response (200) - Valid

Response (200) - Invalid

API Keys

Scoped API keys with granular permissions using bitfield-based authorization. Keys support rate limiting, IP allowlisting, and expiration.

Key Features

FeatureDescription
Scoped PermissionsGranular access control with resource:action format
Rate LimitingPer-key RPM limits (default: 1000, max: 10,000)
IP AllowlistingRestrict key usage to specific IPs or CIDR ranges
ExpirationOptional key expiration in days
HMAC SecurityKeys hashed with HMAC-SHA256 using 32+ byte secret
Usage TrackingAutomatic usage count and last-used timestamp

Key Format

API keys follow the format: ru_<12_char_prefix>_<32_char_secret> (48 characters total)

The raw API key is shown only once during creation. Store it securely - if lost, you must revoke the key and generate a new one.

Generate API Key

Create a new scoped API key with specific permissions.

Headers: Authorization: Bearer <jwt>

Request Body

  • Name
    scopes
    Type
    array
    Description
    Resource permissions (e.g., ["companies:read", "leads:write"])
  • Name
    name
    Type
    string
    Description
    Key name for identification
  • Name
    description
    Type
    string
    Description
    Optional description
  • Name
    expires_days
    Type
    integer
    Description
    Days until expiration (null = never)
  • Name
    rate_limit_rpm
    Type
    integer
    Description
    Requests per minute limit (default: 1000)
  • Name
    ip_allowlist
    Type
    array
    Description
    Allowed IPs/CIDRs (optional)

Request

POST
/auth/apikey

Response (201)

List API Keys

List all API keys for the authenticated user.

Headers: Authorization: Bearer <jwt>

Response Fields

  • Name
    status
    Type
    string
    Description
    Key status: active, revoked, or expired
  • Name
    usage_count
    Type
    integer
    Description
    Total API calls with this key
  • Name
    last_used_at
    Type
    string
    Description
    ISO timestamp of last usage
  • Name
    rate_limit_rpm
    Type
    integer
    Description
    Current RPM limit

Request

GET
/auth/apikeys

Response (200)

Revoke API Key

Revoke an API key immediately. Revoked keys cannot be reactivated.

Headers: Authorization: Bearer <jwt>

Query Parameters

  • Name
    id
    Type
    integer
    Description
    The API key ID to revoke

Request

POST
/auth/apikey/revoke?id=42

Response (200)

Validate API Key

Validate an API key and retrieve user information with resolved scopes.

Request Body

  • Name
    api_key
    Type
    string
    Description
    The API key to validate

Request

POST
/auth/validate-apikey

Response (200) - Valid

Response (200) - Invalid

Get Scope Registry

Get all available resources and their permitted actions.

Headers: Authorization: Bearer <jwt>

Request

GET
/auth/scopes

Response (200)

Check Scope

Check if an API key has a specific scope permission.

Request Body

  • Name
    api_key
    Type
    string
    Description
    The API key to check
  • Name
    scope
    Type
    string
    Description
    Scope to check (e.g., "companies:read")

Request

POST
/auth/scopes/check

Response (200)

Rate Limits & Security

Authentication Rate Limits

EndpointLimitWindow
/auth/register5 requestsPer minute per IP
/auth/login5 requestsPer minute per IP
/auth/login (failed)3 failuresAccount lockout for 15 minutes
/auth/validate-token100 requestsPer minute per IP
/auth/validate-apikey100 requestsPer minute per IP

API Key Rate Limits

Limit TypeDefaultMaximumDescription
Per-key RPM100010,000Configured per key at creation
Per-key daily100,0001,000,000Rolling 24-hour window
IP-based5000-Per IP across all keys

Rate limit headers are returned with each response:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests in window
  • X-RateLimit-Reset: Unix timestamp when limit resets

IP Allowlist Formats

API keys can be restricted to specific IP addresses or ranges:

FormatExampleDescription
Exact IP192.168.1.100Single IP address
CIDR Range192.168.1.0/24IPv4 subnet (256 addresses)
Wildcard192.168.1.*Match any in last octet
IPv62001:db8::/32IPv6 CIDR range

IP Allowlist Example

Security Features

Account Protection

  • Argon2id password hashing (post-quantum resistant)
  • Automatic account lockout after 3 failed login attempts
  • Suspicious activity tracking and IP-based bans
  • JWT token blacklisting for immediate revocation

API Key Security

  • HMAC-SHA256 hashing with 32+ byte secret
  • Automatic key expiration support
  • Per-key rate limiting and usage tracking
  • IP-based access restrictions

Audit & Monitoring

  • Comprehensive audit logging (login, key creation, revocation)
  • Prometheus metrics at /metrics
  • Key usage analytics (count, last used)
  • Suspicious activity alerts

Best Practices

  • Rotate API keys every 90 days
  • Use minimal required scopes
  • Set IP allowlists for production keys
  • Monitor key usage for anomalies

Error Codes

StatusCodeDescription
401unauthorizedMissing or invalid credentials
401token_expiredJWT token has expired
403forbiddenValid credentials but insufficient permissions
403ip_not_allowedRequest IP not in key allowlist
429rate_limit_exceededToo many requests (key or IP limit)
423account_lockedToo many failed login attempts

Admin

Admin endpoints require the admin role.

List Users

List all users with activity summaries.

Headers: Authorization: Bearer <jwt> (admin required)

Query Parameters

  • Name
    limit
    Type
    integer
    Description
    Results per page (default: 50, max: 100)
  • Name
    offset
    Type
    integer
    Description
    Pagination offset

Request

GET
/admin/users

Response (200)

Get User Details

Get detailed information about a specific user.

Headers: Authorization: Bearer <jwt> (admin required)

Query Parameters

  • Name
    id
    Type
    integer
    Description
    User ID

Request

GET
/admin/users/detail?id=1

Response (200)

Update User Role

Update a user's role.

Headers: Authorization: Bearer <jwt> (admin required)

Request Body

  • Name
    user_id
    Type
    integer
    Description
    User ID to update
  • Name
    role
    Type
    string
    Description
    New role: "user" or "admin"

Request

POST
/admin/users/role

Response (200)

Get Audit Logs

Get system audit logs with filtering.

Headers: Authorization: Bearer <jwt> (admin required)

Query Parameters

  • Name
    user_id
    Type
    integer
    Description
    Filter by user ID
  • Name
    event_type
    Type
    string
    Description
    Filter by event type
  • Name
    from
    Type
    string
    Description
    Start date (RFC3339)
  • Name
    to
    Type
    string
    Description
    End date (RFC3339)
  • Name
    limit
    Type
    integer
    Description
    Results per page (default: 50)
  • Name
    offset
    Type
    integer
    Description
    Pagination offset

Request

GET
/admin/audit-logs

Response (200)

Get System Stats

Get system-wide statistics.

Headers: Authorization: Bearer <jwt> (admin required)

Request

GET
/admin/stats

Response (200)

System

Health Check

Check Authentication service health status.

Request

GET
/health

Response (200)

Metrics

Prometheus-formatted metrics.

Request

GET
/metrics

Response

Available Scopes

v2 API keys support the following scopes:

ResourceActions
companiesread, write, delete, admin
leadsread, write, delete, admin
contactsread, write, delete, admin
enrichmentread, write, delete, admin
searchread
adminread, write, delete, admin
usersread, write, delete, admin
apikeysread, write, delete, admin
billingread, write, admin
systemread

Scope format: {resource}:{action}. Example: companies:read grants read access to company data.

Was this page helpful?