Authentication and Access Control

Safe Zone can require bearer tokens for detection, gateway, and policy-management endpoints. Enable authentication in every environment that is reachable outside a tightly controlled internal network.

Enable Authentication

AUTH_ENABLED=true
AUTH_REQUIRE_BEARER_TOKEN=true
AUTH_TOKEN_PERMISSIONS=detect-client=detect:read,gateway-client=gateway:use,policy-admin=patterns:admin|validators:admin|allowlist:admin|blacklist:admin|templates:admin
AUTH_PUBLIC_PATHS=/healthz,/ready

AUTH_TOKEN_PERMISSIONS maps tokens to permissions. Keep tokens in a secret manager and inject them at runtime. The values shown here are examples, not production credentials.

Send a Token

POST /detect
Authorization: Bearer detect-client
Content-Type: application/json

{
  "text": "Contact user@example.com",
  "rid": "request-123"
}

The bearer token is evaluated against the permission required by the endpoint. A valid token without the required permission must not be treated as an administrator token.

Permission Reference

Permission	Allows
detect:read	Run PII, secret, and guardrail detection through /detect.
gateway:use	Call /v1/chat/completions through the protected LLM gateway.
patterns:admin	Create, list, and remove detection patterns.
validators:admin	Manage format and AI validators.
allowlist:admin	Manage values intentionally excluded from detection.
blacklist:admin	Manage explicitly forbidden values.
templates:admin	Import reusable policy templates.
cache:admin	Perform supported administrative cache operations.

Create separate tokens for applications and operators. A service that only calls /detect should not receive policy-management permissions.

Public Endpoints

Health and readiness endpoints are public by default so infrastructure probes can call them without a secret:

• /healthz reports process health.
• /ready reports whether the service is ready to accept traffic.

Keep AUTH_PUBLIC_PATHS limited to non-sensitive probe endpoints. Do not add /detect, the LLM gateway, or management paths to this list.

Legacy Admin Key

Some clients also send X-ADMIN-KEY for compatibility with older administrative flows. New application integrations should use bearer tokens and explicit permissions. If compatibility is required, limit the legacy key to trusted operator paths and plan its removal.

Network Controls

Application authentication is one layer of the deployment boundary. For externally reachable environments, also use:

• TLS at the ingress or gateway.
• Network policies that restrict direct pod access.
• A WAF or API gateway for external exposure.
• Rate limits appropriate to each endpoint.
• A controlled CORS allowlist for browser clients.
• Secret rotation and an incident revocation procedure.

Verification Checklist

1. Call /healthz without a token and confirm the expected probe response.
2. Call /detect without a token and confirm it is rejected.
3. Call /detect with a detect:read token and confirm it succeeds.
4. Call a management endpoint with the detection token and confirm it is rejected.
5. Call the same endpoint with the correct administrative permission.
6. Confirm rejected requests do not expose token values or sensitive request text in logs.