> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yaml
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:

1. Wait `initial-backoff` seconds (default: 0.15s)
2. Double the wait time on each subsequent attempt
3. Stop retrying after `max-retry-duration` seconds total (default: 2.0s)
4. 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

```yaml
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:

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

Then use this token in SDK client initialization:

```python
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:

```python
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](https://developer.onetrust.com/onetrust/docs/ai-guard-tls-certificate-pinning) — Secure the connection between SDK and service
* [Service Configuration](https://developer.onetrust.com/onetrust/docs/ai-guard-service-configuration) — Full configuration reference
* [Troubleshooting](https://developer.onetrust.com/onetrust/docs/ai-guard-troubleshooting) — Common authentication issues