# zalando-incubator/agentic-identity-broker architecture

> Architecture diagram of the GitHub repository zalando-incubator/agentic-identity-broker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zalando-incubator/agentic-identity-broker
- Repository: https://github.com/zalando-incubator/agentic-identity-broker

## Overview

Agentic Identity Broker centralizes OAuth2 delegation, consent, token storage, and gateway-side token exchange for AI agents. A user manages grants and sessions in the web portal; the broker supports OAuth2 authorization and third-party sessions, while a separate Envoy external-processing service performs token exchange and authorization checks in gateway traffic. Other documented capabilities include agent administration, tool approvals, impersonation, and signing-key lifecycle. Connections among unsampled handlers and services are intentionally limited; dashed edges mark documented or plausible but unverified integration points.

Main entry points: [`web/src/App.tsx`](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/App.tsx) (Portal routes), [`internal/ports/storage.go`](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/ports/storage.go) (Storage contracts), [`internal/extproc/server/server.go`](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/server/server.go) (Token exchange server), [`internal/app/handlers.go`](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/app/handlers.go) (Handler wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Consent portal"]
  node_portal_app["Portal routes<br/>[App.tsx]"]
  node_consent_pages["Consent pages"]
  node_grant_page["Grant details"]
  node_session_page["Session management"]
  node_approval_pages["Tool approvals"]
  node_api_client["Portal API client<br/>[client.ts]"]
  node_session_api["Session API<br/>[sessions.ts]"]
end

subgraph group_http["Broker API"]
  node_broker["HTTP server<br/>[server.go]"]
  node_app_handlers["Handler wiring<br/>[handlers.go]"]
  node_consent_handler["Consent handlers"]
  node_approval_handler["Approval handlers"]
  node_admin_handlers["Agent administration<br/>[agents_handler.go]"]
end

subgraph group_identity["Delegation and identity"]
  node_oauth_service["OAuth2 service<br/>[service.go]"]
  node_oauth_sessions["OAuth2 sessions<br/>[service.go]"]
  node_consent_service["Consent and grants<br/>[service.go]"]
  node_approval_service["Tool approval<br/>[service.go]"]
  node_impersonation["Impersonation<br/>[service.go]"]
end

subgraph group_gateway["Gateway processing"]
  node_extproc["Token exchange server<br/>[server.go]"]
  node_ext_authorization["Gateway authorization<br/>[authorizer.go]"]
  node_approval_gate["Approval gate<br/>[gate.go]"]
end

subgraph group_infra["Persistence and security"]
  node_storage_ports["Storage contracts<br/>[storage.go]"]
  node_postgres_approvals[("Approval repository")]
  node_key_lifecycle["Signing-key lifecycle<br/>[engine.go]"]
  node_telemetry["Audit telemetry<br/>[context_handler.go]"]
end

node_user(("User"))
node_upstream(("OAuth2 providers"))
node_gateway_proxy(("Envoy gateway"))

node_user -->|"uses"| node_portal_app
node_portal_app -->|"routes to"| node_consent_pages
node_portal_app -->|"routes to"| node_grant_page
node_portal_app -->|"routes to"| node_session_page
node_portal_app -->|"routes to"| node_approval_pages
node_session_page -->|"loads sessions"| node_session_api
node_session_api -->|"calls"| node_api_client
node_gateway_proxy -.->|"dispatches requests"| node_extproc
node_extproc -->|"evaluates policy"| node_ext_authorization
node_extproc -->|"checks approvals"| node_approval_gate
node_extproc -.->|"exchanges tokens"| node_oauth_service
node_upstream -.->|"OAuth callbacks"| node_oauth_sessions
node_consent_service -->|"uses repositories"| node_storage_ports
node_oauth_sessions -->|"stores sessions"| node_storage_ports
node_approval_service -->|"uses repositories"| node_storage_ports
node_postgres_approvals -->|"implements contracts"| node_storage_ports
node_key_lifecycle -->|"persists keys"| node_storage_ports
node_app_handlers -->|"registers"| node_consent_handler
node_app_handlers -->|"registers"| node_approval_handler
node_consent_handler -.->|"invokes"| node_consent_service
node_approval_handler -->|"invokes"| node_approval_service
node_broker -.->|"serves handlers"| node_app_handlers
node_broker -.->|"logs requests"| node_telemetry

click node_portal_app "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/App.tsx"
click node_consent_pages "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ConsentOverviewPage.tsx"
click node_grant_page "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/AgentGrantDetailPage.tsx"
click node_session_page "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ThirdPartySessionsPage.tsx"
click node_approval_pages "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ToolAuthorizationsPage.tsx"
click node_api_client "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/services/api/client.ts"
click node_session_api "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/services/api/sessions.ts"
click node_broker "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/server.go"
click node_app_handlers "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/app/handlers.go"
click node_consent_handler "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/consent/agent_detail_handler.go"
click node_approval_handler "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/approval/scope_preview_handler.go"
click node_oauth_service "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/oauth2/service.go"
click node_oauth_sessions "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/oauth2session/service.go"
click node_consent_service "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/consent/service.go"
click node_approval_service "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/approval/service.go"
click node_impersonation "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/impersonation/service.go"
click node_admin_handlers "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/admin/agents_handler.go"
click node_extproc "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/server/server.go"
click node_ext_authorization "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/authorization/authorizer.go"
click node_approval_gate "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/approval/gate.go"
click node_storage_ports "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/ports/storage.go"
click node_postgres_approvals "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/storage/postgres/tool_approval_repository.go"
click node_key_lifecycle "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/keylifecycle/engine.go"
click node_telemetry "https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/telemetry/context_handler.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_portal_app,node_consent_pages,node_grant_page,node_session_page,node_approval_pages,node_api_client,node_session_api,node_user toneBlue
class node_broker,node_app_handlers,node_consent_handler,node_approval_handler,node_admin_handlers toneAmber
class node_oauth_service,node_oauth_sessions,node_consent_service,node_approval_service,node_impersonation toneMint
class node_extproc,node_ext_authorization,node_approval_gate toneRose
class node_storage_ports,node_postgres_approvals,node_key_lifecycle,node_telemetry,node_upstream,node_gateway_proxy toneIndigo
```

## Components

### Consent portal

- [Portal routes](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Consent pages](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ConsentOverviewPage.tsx): `web/src/pages/ConsentOverviewPage.tsx`
- [Grant details](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/AgentGrantDetailPage.tsx): `web/src/pages/AgentGrantDetailPage.tsx`
- [Session management](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ThirdPartySessionsPage.tsx): `web/src/pages/ThirdPartySessionsPage.tsx`
- [Tool approvals](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/pages/ToolAuthorizationsPage.tsx): `web/src/pages/ToolAuthorizationsPage.tsx`
- [Portal API client](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/services/api/client.ts): `web/src/services/api/client.ts`
- [Session API](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/web/src/services/api/sessions.ts): `web/src/services/api/sessions.ts`

### Broker API

- [HTTP server](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/server.go): `internal/adapters/http/server.go`
- [Handler wiring](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/app/handlers.go): `internal/app/handlers.go`
- [Consent handlers](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/consent/agent_detail_handler.go): `internal/adapters/http/handlers/consent/agent_detail_handler.go`
- [Approval handlers](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/approval/scope_preview_handler.go): `internal/adapters/http/handlers/approval/scope_preview_handler.go`
- [Agent administration](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/http/handlers/admin/agents_handler.go): `internal/adapters/http/handlers/admin/agents_handler.go`

### Delegation and identity

- [OAuth2 service](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/oauth2/service.go): `internal/domain/oauth2/service.go`
- [OAuth2 sessions](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/oauth2session/service.go): `internal/domain/oauth2session/service.go`
- [Consent and grants](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/consent/service.go): `internal/domain/consent/service.go`
- [Tool approval](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/approval/service.go): `internal/domain/approval/service.go`
- [Impersonation](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/impersonation/service.go): `internal/domain/impersonation/service.go`

### Gateway processing

- [Token exchange server](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/server/server.go): `internal/extproc/server/server.go`
- [Gateway authorization](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/authorization/authorizer.go): `internal/extproc/authorization/authorizer.go`
- [Approval gate](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/extproc/approval/gate.go): `internal/extproc/approval/gate.go`

### Persistence and security

- [Storage contracts](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/ports/storage.go): `internal/ports/storage.go`
- [Approval repository](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/storage/postgres/tool_approval_repository.go): `internal/adapters/storage/postgres/tool_approval_repository.go`
- [Signing-key lifecycle](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/domain/keylifecycle/engine.go): `internal/domain/keylifecycle/engine.go`
- [Audit telemetry](https://github.com/zalando-incubator/agentic-identity-broker/blob/main/internal/adapters/telemetry/context_handler.go): `internal/adapters/telemetry/context_handler.go`

### Other components

- **User**
- **OAuth2 providers**
- **Envoy gateway**

## Connections

- User → Portal routes: uses (evidence: `README.md`)
- Portal routes → Consent pages: routes to (evidence: `web/src/App.tsx`)
- Portal routes → Grant details: routes to (evidence: `web/src/App.tsx`)
- Portal routes → Session management: routes to (evidence: `web/src/App.tsx`)
- Portal routes → Tool approvals: routes to (evidence: `web/src/App.tsx`)
- Session management → Session API: loads sessions
- Session API → Portal API client: calls (evidence: `web/src/services/api/sessions.ts`)
- Envoy gateway → Token exchange server: dispatches requests
- Token exchange server → Gateway authorization: evaluates policy (evidence: `internal/extproc/server/server.go`)
- Token exchange server → Approval gate: checks approvals (evidence: `internal/extproc/server/server.go`)
- Token exchange server → OAuth2 service: exchanges tokens
- OAuth2 providers → OAuth2 sessions: OAuth callbacks
- Consent and grants → Storage contracts: uses repositories (evidence: `internal/domain/consent/service.go`)
- OAuth2 sessions → Storage contracts: stores sessions (evidence: `internal/domain/oauth2session/service.go`)
- Tool approval → Storage contracts: uses repositories (evidence: `internal/domain/approval/service.go`)
- Approval repository → Storage contracts: implements contracts (evidence: `internal/adapters/storage/postgres/tool_approval_repository.go`)
- Signing-key lifecycle → Storage contracts: persists keys (evidence: `internal/domain/keylifecycle/engine.go`)
- Handler wiring → Consent handlers: registers (evidence: `internal/app/handlers.go`)
- Handler wiring → Approval handlers: registers (evidence: `internal/app/handlers.go`)
- Consent handlers → Consent and grants: invokes
- Approval handlers → Tool approval: invokes (evidence: `internal/adapters/http/handlers/approval/scope_preview_handler.go`)
- HTTP server → Handler wiring: serves handlers
- HTTP server → Audit telemetry: logs requests
