Auth Profiles

Two authentication modes for different agent use cases.

Overview

RelayPlane distinguishes between two types of authentication to help you enforce appropriate security policies:

API Authentication

API keys are for your own systems. They have full access to run in any execution mode:

1# API key format
2RELAYPLANE_API_KEY=rp_xxx
3
4# Usage
5curl http://localhost:4100/v1/chat/completions \
6  -H "Authorization: Bearer rp_xxx" \
7  -H "X-RelayPlane-Agent: my-internal-agent" \
8  -d '{...}'

• ✅ Can run in interactive mode
• ✅ Can run in background mode
• ✅ Can run on schedules
• ✅ Full audit trail in ledger

Consumer Authentication

Consumer tokens are for end-users interacting with your agents. They have restricted permissions:

1# Consumer token (usually issued per-session)
2X-RelayPlane-Consumer-Token: ct_user_abc123
3
4# Usage
5curl http://localhost:4100/v1/chat/completions \
6  -H "X-RelayPlane-Consumer-Token: ct_user_abc123" \
7  -H "X-RelayPlane-Agent: customer-support-bot" \
8  -d '{...}'

Execution Modes

• interactive, User-initiated, synchronous. A human is waiting for the response. Safe for both auth types.
• background, System-initiated, async processing. No user waiting. API auth only (consumer triggers auth_risk).
• scheduled, Cron or timer-triggered. No user context. API auth only (consumer triggers auth_risk).

1// Set execution mode via header
2X-RelayPlane-Execution-Mode: interactive  // default
3X-RelayPlane-Execution-Mode: background   // for async processing
4X-RelayPlane-Execution-Mode: scheduled    // for cron jobs

Auth Risk Detection

When consumer auth is used with background or scheduled mode, the run is flagged:

1// Run entry when auth_risk is detected
2{
3  "run_id": "run_123",
4  "auth_type": "consumer",
5  "execution_mode": "background",
6  "auth_risk": true,
7  // This run will be flagged in analytics and can trigger alerts
8}

You can configure policies to block or require approval for auth_risk runs:

1{
2  "name": "Block Consumer Background",
3  "type": "custom",
4  "conditions": [
5    { "field": "auth_risk", "operator": "eq", "value": true }
6  ],
7  "action": { "type": "deny" }
8}

Compliance Modes

• recommended, Default. Strict mode that blocks consumer auth in non-interactive modes.
• permissive, Allows consumer auth in all modes, but still logs auth_risk flag. Use when you understand the implications.

1// Set at workspace level
2{
3  "workspace_id": "ws_123",
4  "compliance_mode": "recommended",  // or "permissive"
5}

Credential Quarantine

The proxy automatically quarantines credentials that return consecutive auth failures. After 2 consecutive 401 responses, a credential is quarantined for 1 hour and the proxy falls back to the next credential in the pool.

1# Credential quarantine behavior
2# - 2 consecutive 401 auth failures trigger quarantine
3# - Quarantine duration: 1 hour
4# - Proxy falls back to the next credential in the pool
5# - Quarantine resets automatically after the duration expires

Best Practices

• Use API keys for automation, Background jobs, scheduled tasks, and internal tools should use API authentication.
• Use consumer tokens for users, Chatbots and customer-facing agents should use consumer authentication.
• Set appropriate scopes, Consumer tokens should have limited scopes (specific agents, rate limits).
• Monitor auth_risk, Set up alerts for auth_risk runs to catch misconfigurations early.

Next Steps

• Setting up Policies
• Team Collaboration
• Teams API Reference