Configuration Guide
For administrators setting up Rivaro for their development team. Covers AppContexts, detection keys, rate limits, and organization requirements.
Where to find it in the app
AppContext and detection-key configuration are administered from two adjacent surfaces:
| What | Where in the app |
|---|---|
| AppContexts (provider routing, allowed models, detectors, rate limits) | Dashboard → Administration → AI Estate → RUNTIME stage → AI Agents list |
| Detection keys (proxy authentication tokens) | Dashboard → Administration → API Credentials |
| Org status | Dashboard → Administration → Org Management |
The developer then uses the detection key and your Rivaro proxy URL to start sending traffic — see the Use Hosted Rivaro guide.
Overview
Before a developer can send traffic through the proxy, an administrator needs to:
- Create an AppContext — defines which AI provider to proxy to
- Create a Detection Key — authenticates proxy requests and links to the AppContext
- Optionally configure — rate limits, allowed models, enabled detectors
AppContexts
An AppContext is the core configuration object. It tells Rivaro which AI provider adapter to use, which models are allowed, which detectors to enable, and what rate limits apply.
Creating an AppContext
In the Rivaro dashboard, open Administration → AI Estate → RUNTIME. The AI Agents (AppContexts) list is here. Click Add AppContext, pick your provider adapter, and fill in the form.
| Field | Required | Description |
|---|---|---|
| Name | Yes | Display name (e.g. "Production OpenAI", "Staging Claude") |
| Adapter type | Yes | Provider identifier (e.g. gpt-4, claude-3-opus, azure-openai) |
| Allowed models | No | Restrict which models can be requested. If empty, all models are allowed. |
| Enabled detectors | No | Which risk categories to scan for. If empty, all detectors run. |
| Rate limit | No | Max requests per minute for this context |
| Monthly quota | No | Max total requests per month |
Configuration options
The AppContext has a flexible configuration map for provider-specific settings:
| Key | Provider | Description |
|---|---|---|
allowed_models | All | Array of permitted model names (e.g. ["gpt-4", "gpt-3.5-turbo"]) |
azureResourceName | Azure | Your Azure OpenAI resource name |
azureDeploymentName | Azure | Default deployment name |
bedrockModelId | Bedrock | Full Bedrock model ARN |
bedrockModelFormat | Bedrock | claude, llama, mistral, titan, or converse |
projectId | Vertex AI | GCP project ID |
location | Vertex AI | GCP region (default: us-central1) |
Governance fields
For organizations with governance requirements, AppContexts also support:
| Field | Description |
|---|---|
| Owner | Team or person responsible for this context |
| Department | Organizational department |
| Data classification | Sensitivity level of data flowing through |
| Purpose | Description of what this context is used for |
Detection Keys
A detection key authenticates proxy requests and links them to an AppContext. Each key is bound to exactly one AppContext.
Creating a key
Open Administration → API Credentials and click Create key.
| Field | Required | Description |
|---|---|---|
| Name | Yes | Descriptive name (e.g. "Production Key", "CI/CD Pipeline") |
| AppContext | Yes | Which AppContext this key routes to |
On creation, the full key is displayed once:
detect_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345
Save this immediately. The full key cannot be retrieved after this screen. Only the prefix and last four characters are stored for display.
Key lifecycle
| Action | How | Effect |
|---|---|---|
| Create | API Credentials → Create key | Key is active immediately |
| Revoke | API Credentials → row's ⋮ menu → Revoke | Key permanently stops working |
| Update | API Credentials → row's ⋮ menu → Edit | Change name or set expiration |
| Expire | Automatic | Key stops working after the expiration timestamp |
Key properties
| Property | Description |
|---|---|
id | Unique key identifier |
displayKey | Masked display (prefix…last4) |
name | Human-readable name |
appContextId | Linked AppContext |
createdBy | Email of the creator |
createdAt | Creation timestamp |
lastUsedAt | Last successful authentication |
usageCount | Total requests made with this key |
expiresAt | Optional expiration timestamp |
Best practices
- One key per environment — separate keys for production, staging, and development so you can revoke independently
- One key per service — if multiple services use the proxy, give each its own key for usage tracking
- Set expiration — for temporary access (contractors, trials), set an expiration date
- Revoke promptly — if a key is compromised, revoke it immediately from API Credentials
Rate Limits
Rivaro enforces rate limits at multiple levels.
Per-AppContext limits
Set the Rate limit field on the AppContext form (Administration → AI Estate → RUNTIME → edit AppContext) to limit how many requests per minute can flow through that context. This is the primary knob for controlling proxy throughput.
Global defaults
If no AppContext-level limit is set, global defaults apply:
| Scope | Default | Description |
|---|---|---|
| Per API key | 100 req/min | Requests per detection key |
| Per IP | 60 req/min | Requests from the same IP |
| Auth endpoints | 10 req/min | Login/auth attempts |
Rate limit response headers
When rate limits are active, every response includes:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests for this window |
X-RateLimit-Remaining | Remaining requests in current window |
X-RateLimit-Reset | Timestamp when the window resets |
When the limit is exceeded, the response is 429 Too Many Requests with a Retry-After header (in seconds).
Organization Requirements
Organization status
The organization must be in ACTIVE status for the proxy to work. Status is visible at Administration → Org Management. Other statuses and their effects:
| Status | Proxy | Dashboard | Notes |
|---|---|---|---|
| ACTIVE | Works | Works | Normal operation |
| TRIAL | Works | Works | Trial period with usage limits |
| TRIAL_EXPIRED | Blocked | Limited | Upgrade required |
| CANCELED | Blocked | Read-only | Reactivate to resume |
| ARCHIVED | Blocked | Blocked | Contact support |
When the proxy is blocked due to organization status, developers receive a 403 error:
{"error": "Organization is not active"}
Giving credentials to your developers
After setup, your developers need two things:
- Proxy base URL — your Rivaro instance URL (e.g.
https://your-org.rivaro.ai) - Detection key — the
detect_live_...key you created
They will also need their own AI provider API key (OpenAI, Anthropic, etc.). Rivaro does not store provider credentials — developers pass them in each request via the standard provider auth header.
See the Use Hosted Rivaro guide for the exact SDK configuration your developers need.
Next steps
- Use Hosted Rivaro — Share with your developers
- Enforcement & Policies — Configure what happens when violations are detected
- Understanding Detections — What Rivaro scans for