Session Endpoints

Agent sessions represent an agent acting on behalf of a user or autonomously. Sessions scope credentials and enforce policy.

Create Session

POST /api/v1/sessions

Headers

• Authorization: Bearer <agentApiKey>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "agentId": "agent_01j...",
  "userId": "usr_01j...",
  "requestedScopes": ["read:customers"],
  "ttl": 3600,
  "context": {
    "taskId": "task-123",
    "purpose": "summarize customer history"
  }
}

userId is optional for autonomous (unattended) agent sessions.

Response 201

{
  "data": {
    "sessionId": "sess_01j...",
    "credentialToken": "En0KH...",
    "grantedScopes": ["read:customers"],
    "expiresAt": "2026-03-18T14:00:00Z"
  }
}

Proxy Request

POST /api/v1/sessions/{sessionId}/proxy

Forward a request to an external API through Bulwark's credential proxy.

Headers

• Authorization: Bearer <credentialToken>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "credentialId": "cred_01j...",
  "method": "GET",
  "url": "https://api.github.com/repos/owner/repo",
  "headers": {
    "Accept": "application/vnd.github+json"
  }
}

Response 200

The proxied response is returned as-is, with Bulwark headers added:

X-Bulwark-Session: sess_01j...
X-Bulwark-Audit: audit_01j...

Complete Session

POST /api/v1/sessions/{sessionId}/complete

Marks the session as completed and invalidates the credential token.

Response 200

{
  "data": {
    "sessionId": "sess_01j...",
    "status": "completed",
    "completedAt": "2026-03-18T13:30:00Z",
    "proxyCallCount": 5
  }
}

Attenuate Token

POST /api/v1/sessions/{sessionId}/attenuate

Create a sub-token with reduced scopes for delegating to a sub-agent.

Body

{
  "scopes": ["read:customers"],
  "ttl": 600,
  "caveats": [
    { "type": "resource", "value": "customer_id:cust_abc" }
  ]
}

Response 200

{
  "data": {
    "token": "En0KH...",
    "scopes": ["read:customers"],
    "expiresAt": "2026-03-18T13:40:00Z"
  }
}

Get Session

GET /api/v1/sessions/{sessionId}

Response 200

{
  "data": {
    "sessionId": "sess_01j...",
    "agentId": "agent_01j...",
    "userId": "usr_01j...",
    "grantedScopes": ["read:customers"],
    "status": "active",
    "createdAt": "2026-03-18T13:00:00Z",
    "expiresAt": "2026-03-18T14:00:00Z"
  }
}