Platform Architecture

Bulwark is built on a multi-layer architecture designed for the agentic era — where AI agents are first-class principals alongside human users.

Core Components

API Server (Go/Fiber)

The central API server handles all authentication, authorization, and credential operations. Built in Go using Fiber for high throughput and low latency.

  • REST API with JSON request/response
  • JWT + Biscuit token issuance and validation
  • Middleware for tenant isolation
  • Rate limiting per tenant/agent

Agent Registry

The Agent Registry manages the lifecycle of AI agent principals:

  • Agent registration and API key issuance
  • Trust level management (low, medium, high, critical)
  • Scope definition and enforcement
  • Agent revocation and key rotation

Credential Proxy

The Credential Proxy sits between agents and external APIs:

Agent → Bulwark Proxy → External API
         ↓
    (injects credentials,
     enforces policy,
     logs to audit trail)

Agents never see raw credentials. The proxy validates the agent's token, checks policy, injects the appropriate credential, and forwards the request.

Token Vault

Stores third-party OAuth tokens (GitHub, Slack, etc.) on behalf of agents:

  • Encrypted at rest using AES-256-GCM
  • Per-agent access control
  • Automatic refresh handling
  • Audit logging on every access

Storage Layer

| Component | Purpose | |------------|------------------------------------------| | PostgreSQL | Persistent store for all entities | | Valkey | Session cache, token blacklist, rate limits| | Secret Vault | Encrypted secrets, API keys |

Data Flow

Human Authentication

1. User submits credentials
2. API validates and issues JWT (short-lived) + Refresh token
3. Client stores tokens; sends JWT on subsequent requests
4. JWT validated per-request (no DB lookup for valid tokens)

Agent Authentication

1. Agent presents API key on startup
2. API validates key, issues Biscuit token with scopes
3. Agent presents Biscuit token per request
4. Token validated; scopes checked against policy
5. Delegated tokens can be attenuated by the agent for sub-tasks

Proxied Credential Request

1. Agent calls POST /api/v1/sessions/{id}/proxy
2. Bulwark validates agent Biscuit token
3. Policy engine checks FGA rules
4. Credential retrieved from vault (decrypted)
5. Request forwarded to external API with credential injected
6. Response returned; audit event written

Multi-Tenancy

Every entity in Bulwark belongs to a tenant. Tenant isolation is enforced at every layer:

  • Database row-level security by tenant_id
  • API key scoped to tenant
  • X-Bulwark-Tenant header required on all requests
  • Audit logs partitioned by tenant

Security Model

  • Credentials at rest: AES-256-GCM encryption
  • Credentials in transit: TLS 1.3 minimum
  • Tokens: Short-lived JWTs (15 min) + Biscuit tokens with expiry
  • Secrets: Never logged, never returned in plaintext after creation
  • Audit trail: Immutable append-only log per tenant