Service Accounts

Overview

Service Accounts provide stateless API keys (sak_live_* / sak_test_*) that authenticate against the management API without JWT tokens, cookies, or browser sessions. They are designed for:

• CI/CD pipelines — Sync gateway config on deploy
• Automation scripts — Rotate API keys, update routes
• Monitoring tools — Query analytics and health status

Key Format

Service account keys use a distinct prefix for easy identification:

Keys are hashed before storage. The plaintext key is shown only once at creation time.

Granular Permissions

Each service account is assigned specific permissions that control what it can access:

// Example: CI/CD pipeline only needs gateway sync
{
  "permissions": ["gateway:sync", "routes:read"]
}

// Example: Monitoring tool needs read-only analytics
{
  "permissions": ["analytics:read", "status:read"]
}

The requirePermission() middleware checks permissions on every request. JWT-authenticated users (humans) bypass permission checks and have full access.

IP Whitelisting

Each service account can have an IP whitelist. If configured, requests from non-whitelisted IPs are rejected with 403 Forbidden, even if the key is valid.

This is critical for CI/CD runners with known static IPs.

Usage

Authenticate by passing the service account key as a Bearer token:

curl https://api.nolxy.com/api/v1/gateway/sync \
  -H "Authorization: Bearer sak_live_abc123..." \
  -H "Content-Type: application/json" \
  -d @nolxy.config.json

The auth middleware detects the sak_ prefix and routes to service account validation instead of JWT verification. No cookies or sessions are involved.

Audit Trail

All actions performed by service accounts are logged in the audit trail with the service account name and ID, making it easy to track which automation performed which change.

The lastUsed timestamp and IP are updated on every request (fire-and-forget) for monitoring purposes.

Plan Requirements

Service Accounts are available on Pro plans and above.