Routes API

Routes tell the Proxy Gateway how to inject credentials into outbound API requests. All endpoints are nested under /secrets/routes and require tenant-level authentication.

Create Route

POST /secrets/routes

Auth: Tenant API key Request Body:

{
  secretId: string;       // ID of the secret to inject
  hostPattern: string;    // Target host (e.g., "api.openai.com", "*.anthropic.com")
  pathPattern?: string;   // Path glob (default: "/*")
  method?: string;        // HTTP method filter (default: "*")
  injectAs: string;       // "header" | "query" | "body"
  injectKey: string;      // Header name, query param, or body field
  injectFormat?: string;  // Format string (default: "{value}")
  priority?: number;      // Higher = checked first (default: 0)
  enabled?: boolean;      // Toggle route (default: true)
}

Response (201):

{
  "ok": true,
  "data": {
    "id": "route-uuid",
    "secretId": "secret-uuid",
    "hostPattern": "api.openai.com",
    "pathPattern": "/*",
    "method": "*",
    "injectAs": "header",
    "injectKey": "Authorization",
    "injectFormat": "Bearer {value}",
    "priority": 0,
    "enabled": true,
    "createdAt": "2026-03-26T12:00:00Z"
  }
}

Examples

curl -X POST http://localhost:3200/secrets/routes \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "secretId": "openai-secret-id",
    "hostPattern": "api.openai.com",
    "pathPattern": "/*",
    "injectAs": "header",
    "injectKey": "Authorization",
    "injectFormat": "Bearer {value}"
  }'

curl -X POST http://localhost:3200/secrets/routes \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "secretId": "anthropic-secret-id",
    "hostPattern": "api.anthropic.com",
    "pathPattern": "/*",
    "injectAs": "header",
    "injectKey": "x-api-key",
    "injectFormat": "{value}"
  }'

curl -X POST http://localhost:3200/secrets/routes \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "secretId": "legacy-secret-id",
    "hostPattern": "api.legacy-service.com",
    "pathPattern": "/*",
    "injectAs": "query",
    "injectKey": "apiKey",
    "injectFormat": "{value}"
  }'

List Routes

GET /secrets/routes

Auth: Tenant API key Response:

{
  "ok": true,
  "data": [
    {
      "id": "route-uuid-1",
      "secretId": "secret-uuid",
      "hostPattern": "api.openai.com",
      "pathPattern": "/*",
      "injectAs": "header",
      "injectKey": "Authorization",
      "injectFormat": "Bearer {value}",
      "priority": 0,
      "enabled": true
    }
  ]
}

Update Route

PUT /secrets/routes/:id

Auth: Tenant API key Request Body: Any subset of the create fields (partial update):

{
  hostPattern?: string;
  pathPattern?: string;
  method?: string;
  injectAs?: string;
  injectKey?: string;
  injectFormat?: string;
  priority?: number;
  enabled?: boolean;
}

# Disable a route
curl -X PUT http://localhost:3200/secrets/routes/route-uuid \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Delete Route

DELETE /secrets/routes/:id

Auth: Tenant API key Response:

{
  "ok": true,
  "data": { "deleted": "route-uuid" }
}

Route Matching

When the proxy receives a request, it matches routes in priority order (highest first). The first matching route wins. A route matches when:

hostPattern matches the target host (supports * wildcards)
pathPattern matches the request path (supports /* glob)
method matches the HTTP method (or * for any)
enabled is true

Priority Example

// Priority 10: Trading API gets privileged credentials
{ hostPattern: "api.example.com", pathPattern: "/v2/trading/*", priority: 10 }

// Priority 0: Everything else gets read-only credentials
{ hostPattern: "api.example.com", pathPattern: "/*", priority: 0 }

A request to api.example.com/v2/trading/orders matches the priority-10 route. A request to api.example.com/v1/data matches the priority-0 fallback.

Restricted inject headers

Some injectKey header names are rejected at route-create time. Hop-by-hop and framing-sensitive headers (connection, content-length, host, transfer-encoding, etc.) are unconditionally blocked. Session-cookie headers (Cookie and Set-Cookie, matched case-insensitively) are blocked by default and only become injectable when the operator sets STEWARD_ALLOW_COOKIE_INJECTION=true. Injecting a raw Cookie replays a whole browser session: there is no scoping, no revocation handle, and no Set-Cookie rotation path, so the blast radius is the entire session. The preferred pattern is a scoped broker read token injected as Authorization: Bearer <token> — revocable, auditable, and narrowed per grant. Raw session replay stays available for hosts that only speak cookies, but as a deliberate operator opt-in rather than an implicit default. Existing routes are validated at create time, so a route created before this default took effect keeps working; the flag only gates creation of new cookie-injecting routes.

​Routes API

​Create Route

​Examples

​List Routes

​Update Route

​Delete Route

​Route Matching

​Priority Example

​Restricted inject headers