/

API Authentication

The AegisWire Go control plane API supports multiple authentication methods depending on the caller type. All API requests must be authenticated except health checks (/healthz, /readyz).

Authentication Methods

The admin web interface authenticates using HTTP-only session cookies. This method is used by the browser-based admin UI at /admin/ and is not recommended for programmatic access.

Session properties:

  • Cookie: HttpOnly, Secure, SameSite=Strict
  • Inactivity timeout: configurable
  • Absolute timeout: configurable
  • All sessions are audit-logged with: admin user ID, session start, source IP, user agent

To authenticate, submit credentials to the admin login page at /admin/login. On success, the server sets a session cookie.

API Key (Machine-to-Machine)

For programmatic access and automation, use an API key:

Authorization: Bearer <api_key>

API keys are generated in the admin interface or via POST /v1/admin/api-keys. Each key is:

  • Scoped to a specific tenant context
  • Assigned an RBAC role
  • Revocable at any time
  • Audit-logged on every use

List existing keys via GET /v1/admin/api-keys.

Device Credential (Client Devices)

Client devices authenticate using credentials received during enrollment (/v1/enroll). The device credential is cryptographically bound to the device and used for policy refresh, gateway directory fetch, and session establishment.

OIDC / SAML (Federated Identity)

When an external identity provider is configured, users and devices can authenticate via:

  • OIDC: Login redirect at /admin/login/oidc, enrollment at /v1/enroll/oidc
  • SAML: Login redirect at /admin/login/saml, enrollment at /v1/enroll/saml

The control plane validates tokens against the configured provider. Any validation failure results in immediate rejection with no fallback to a weaker authentication mode.

Security Rules

Rate Limiting

All authentication endpoints are rate-limited:

  • Login: Maximum failed attempts per source IP within a time window
  • API requests: Per-key rate limits configurable by the administrator
  • Exceeding the rate limit returns HTTP 429 Too Many Requests

Account Lockout

After a configurable number of consecutive failed login attempts:

  1. The account is locked
  2. An admin notification is generated
  3. The account remains locked until an administrator unlocks it or the lockout timeout expires
  4. The lockout event is audit-logged

Audit Logging

Every authentication event is audit-logged:

Event Logged Fields
Successful login user_id, source_ip, user_agent, auth_method, timestamp
Failed login username (attempted), source_ip, user_agent, failure_reason, timestamp
API key used key_id, source_ip, endpoint, timestamp
Session expired session_id, user_id, reason (timeout/manual), timestamp
Lockout triggered username, source_ip, attempt_count, timestamp

Error Responses

All authentication errors return structured JSON:

{
  "error": "unauthorized",
  "detail": "Invalid credentials",
  "request_id": "req_abc123def456"
}

HTTP Status Codes

Code Meaning
401 Unauthorized Missing or invalid credentials
403 Forbidden Valid credentials but insufficient permissions
429 Too Many Requests Rate limit exceeded

The response body does not include specific details about which credential component failed (to prevent enumeration attacks).

RBAC Model

API permissions follow the control plane's role-based access control model. Roles are managed via the admin interface and can be granted or revoked via /v1/admin/rbac/grant and /v1/admin/rbac/revoke.

Request Format

All API requests that include a body must use:

  • Content-Type: application/json
  • UTF-8 encoded JSON body

All API responses use:

  • Content-Type: application/json
  • UTF-8 encoded JSON body