AI Guard: Authentication & Authorization

AI Guard supports two authorization modes for validating bearer tokens on classification and metric requests. The mode is configured in the service.authorization section of the configuration file.

Authorization Modes

Mode	Type Value	Description	Use Case
OneTrust	`onetrust`	Validates tokens against a remote OneTrust endpoint	Production deployments
Shared Secret	`shared-secret`	Compares tokens against a local file	Development and testing

OneTrust Token Validation (Production)

In this mode, the service forwards the client's bearer token to a remote OneTrust validation endpoint. If the endpoint returns 200 OK, the request is authorized. Any other status results in 401 Unauthorized.

Configuration

service:
  authorization:
    type: onetrust
    validation-endpoint: "${OT_SERVICE_BASE_URL:-https://your-tenant.onetrust.com}/api/label-manager/v2/custom-classifiers?searchTerm=4a72ec89d3b4798c"
    trusted-root-path: ${VALIDATION_ENDPOINT_TRUSTED_ROOT_PATH:-}
    trusted-root-address: ${VALIDATION_ENDPOINT_TRUSTED_ROOT_ADDRESS:-}
    initial-backoff: 0.15
    max-retry-duration: 2.0
    cache-max-capacity: 1000
    cache-ttl: 300

Configuration Fields

Field	Env Var	Default	Description
`validation-endpoint`	`OT_SERVICE_BASE_URL`	—	URL the server calls to validate bearer tokens
`trusted-root-path`	`VALIDATION_ENDPOINT_TRUSTED_ROOT_PATH`	—	Optional. PEM CA certificate for the validation endpoint
`trusted-root-address`	`VALIDATION_ENDPOINT_TRUSTED_ROOT_ADDRESS`	—	Optional. Override address (`host:port`) for the validation endpoint
`initial-backoff`	—	`0.15`	Seconds before the first retry on validation failure (exponential backoff)
`max-retry-duration`	—	`2.0`	Maximum total seconds spent retrying before failing
`cache-max-capacity`	—	`1000`	Maximum number of validated tokens to cache
`cache-ttl`	—	`300`	Seconds a cached token remains valid before re-validation

Token Caching

To reduce latency and load on the OneTrust tenant, validated tokens are cached locally:

cache-max-capacity — Maximum number of tokens held in cache. When the cache is full, the least recently used token is evicted.
cache-ttl — How long (in seconds) a validated token remains in cache before the service re-validates it with OneTrust.

Retry Behavior

When a validation request to the OneTrust endpoint fails (network error, timeout, etc.), the service retries with exponential backoff:

Wait initial-backoff seconds (default: 0.15s)
Double the wait time on each subsequent attempt
Stop retrying after max-retry-duration seconds total (default: 2.0s)
If all retries are exhausted, return 401 Unauthorized to the client

Shared Secret Authorization (Development)

The simplest mode — the bearer token is loaded from a local file and compared directly against the client's token.

Configuration

service:
  authorization:
    type: shared-secret
    shared-secret-path: "${CLASSIFICATION_TOKEN_PATH:-/run/secrets/classification-token}"

Configuration Fields

Field	Env Var	Default	Description
`shared-secret-path`	`CLASSIFICATION_TOKEN_PATH`	`/run/secrets/classification-token`	Path to a file containing the bearer token

Creating the Secret File

Create a file containing the shared secret token:

echo "my-secret-token" > /run/secrets/classification-token

Then use this token in SDK client initialization:

client = AIGuardClient(
    "https://ai-guard.example.com:4443",
    token="my-secret-token",
    agent_id="my-agent",
    platform=AIPlatform.AMAZON_BEDROCK,
)

⚠️
Security Warning
Shared secret mode is intended for development and testing only. For production deployments, always use OneTrust token validation.

Client Authentication

From the SDK perspective, both modes work identically. The client sends a bearer token in the Authorization header:

from ai_guard import AIGuardClient
from ai_guard.api import AIPlatform

# Works with both authorization modes
client = AIGuardClient(
    "https://ai-guard.example.com:4443",
    token="your-api-key",
    agent_id="my-agent",
    platform=AIPlatform.AMAZON_BEDROCK,
)

The token parameter is sent as Authorization: Bearer <token> on every request.

What's Next?

TLS & Certificate Pinning — Secure the connection between SDK and service
Service Configuration — Full configuration reference
Troubleshooting — Common authentication issues