# ory/hydra architecture

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

- Interactive diagram: https://gitdiagram.com/ory/hydra
- Repository: https://github.com/ory/hydra

## Overview

Ory Hydra is a standalone OAuth 2.0 and OpenID Connect server that delegates user authentication and consent to an external application. A client or user agent starts an authorization flow; Hydra coordinates login and consent, issues a code or token, and supports subsequent token validation and lifecycle operations. The repository also provides client and JWKS administration, device authorization, trusted JWT grants, and operational CLI/server configuration. The source index confirms the server handler’s connections to these subsystems; several feature-specific implementation links are documented by capability or remain unverified because their sources were not excerpted.

Main entry points: [`cmd/server/handler.go`](https://github.com/ory/hydra/blob/master/cmd/server/handler.go) (HTTP server routing), [`oauth2/handler.go`](https://github.com/ory/hydra/blob/master/oauth2/handler.go) (OAuth endpoints), [`consent/handler.go`](https://github.com/ory/hydra/blob/master/consent/handler.go) (Login and consent orchestration), [`fosite/authorize_request_handler.go`](https://github.com/ory/hydra/blob/master/fosite/authorize_request_handler.go) (OAuth/OIDC engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["HTTP server routing<br/>[handler.go]"]
  node_config["Configuration and wiring<br/>[config.go]"]
end

subgraph group_protocol["OAuth and OIDC"]
  node_oauth_handler["OAuth endpoints<br/>[handler.go]"]
  node_fosite["OAuth/OIDC engine"]
  node_device_flow["Device authorization<br/>[token_handler.go]"]
end

subgraph group_identity["Login and consent"]
  node_login_consent["Login and consent orchestration<br/>[handler.go]"]
  node_flow_state["Authorization flow state<br/>[flow.go]"]
end

subgraph group_admin["Administration"]
  node_client_api["Client management<br/>[handler.go]"]
  node_jwk_api["JWKS management<br/>[handler.go]"]
  node_trust_api["Trusted JWT grants<br/>[handler.go]"]
  node_cli["CLI operations<br/>[cmd_perform.go]"]
end

subgraph group_state["Keys and persistence"]
  node_key_manager["Signing key manager<br/>[manager.go]"]
  node_hsm["Hardware key manager<br/>[manager_hsm.go]"]
  node_sql_store[("SQL persistence<br/>[persister.go]")]
  node_client_manager["Client storage and auth<br/>[manager.go]"]
end

node_user_agent(("OAuth client / user agent"))
node_identity_app(("Login and consent app"))
node_admin_user(("Operator"))

node_user_agent -->|"sends requests"| node_server
node_server -->|"routes to"| node_oauth_handler
node_oauth_handler -->|"calls protocol"| node_fosite
node_fosite -.->|"requests interaction"| node_login_consent
node_login_consent -->|"redirects for decisions"| node_identity_app
node_login_consent -->|"manages flow state"| node_flow_state
node_oauth_handler -.->|"redirects with result"| node_user_agent
node_user_agent -.->|"exchanges code"| node_oauth_handler
node_server -.->|"serves device flow"| node_device_flow
node_server -->|"routes to"| node_client_api
node_server -->|"routes to"| node_jwk_api
node_server -.->|"routes to"| node_trust_api
node_admin_user -.->|"runs commands"| node_cli
node_cli -.->|"calls admin API"| node_server
node_server -->|"uses configuration"| node_config
node_oauth_handler -.->|"uses signing keys"| node_key_manager
node_key_manager -->|"delegates key operations"| node_hsm
node_oauth_handler -.->|"persists OAuth state"| node_sql_store
node_client_api -.->|"manages clients"| node_client_manager
node_client_manager -->|"stores client records"| node_sql_store

click node_server "https://github.com/ory/hydra/blob/master/cmd/server/handler.go"
click node_config "https://github.com/ory/hydra/blob/master/driver/config/config.go"
click node_oauth_handler "https://github.com/ory/hydra/blob/master/oauth2/handler.go"
click node_fosite "https://github.com/ory/hydra/blob/master/fosite/authorize_request_handler.go"
click node_device_flow "https://github.com/ory/hydra/blob/master/fosite/handler/rfc8628/token_handler.go"
click node_login_consent "https://github.com/ory/hydra/blob/master/consent/handler.go"
click node_flow_state "https://github.com/ory/hydra/blob/master/flow/flow.go"
click node_client_api "https://github.com/ory/hydra/blob/master/client/handler.go"
click node_jwk_api "https://github.com/ory/hydra/blob/master/jwk/handler.go"
click node_trust_api "https://github.com/ory/hydra/blob/master/oauth2/trust/handler.go"
click node_cli "https://github.com/ory/hydra/blob/master/cmd/cmd_perform.go"
click node_key_manager "https://github.com/ory/hydra/blob/master/jwk/manager.go"
click node_hsm "https://github.com/ory/hydra/blob/master/hsm/manager_hsm.go"
click node_sql_store "https://github.com/ory/hydra/blob/master/persistence/sql/persister.go"
click node_client_manager "https://github.com/ory/hydra/blob/master/client/manager.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_server,node_config,node_user_agent toneBlue
class node_oauth_handler,node_fosite,node_device_flow toneAmber
class node_login_consent,node_flow_state toneMint
class node_client_api,node_jwk_api,node_trust_api,node_cli toneRose
class node_key_manager,node_hsm,node_sql_store,node_client_manager,node_identity_app,node_admin_user toneIndigo
```

## Components

### Server runtime

- [HTTP server routing](https://github.com/ory/hydra/blob/master/cmd/server/handler.go): `cmd/server/handler.go`
- [Configuration and wiring](https://github.com/ory/hydra/blob/master/driver/config/config.go): `driver/config/config.go`

### OAuth and OIDC

- [OAuth endpoints](https://github.com/ory/hydra/blob/master/oauth2/handler.go): `oauth2/handler.go`
- [OAuth/OIDC engine](https://github.com/ory/hydra/blob/master/fosite/authorize_request_handler.go): `fosite/authorize_request_handler.go`
- [Device authorization](https://github.com/ory/hydra/blob/master/fosite/handler/rfc8628/token_handler.go): `fosite/handler/rfc8628/token_handler.go`

### Login and consent

- [Login and consent orchestration](https://github.com/ory/hydra/blob/master/consent/handler.go): `consent/handler.go`
- [Authorization flow state](https://github.com/ory/hydra/blob/master/flow/flow.go): `flow/flow.go`

### Administration

- [Client management](https://github.com/ory/hydra/blob/master/client/handler.go): `client/handler.go`
- [JWKS management](https://github.com/ory/hydra/blob/master/jwk/handler.go): `jwk/handler.go`
- [Trusted JWT grants](https://github.com/ory/hydra/blob/master/oauth2/trust/handler.go): `oauth2/trust/handler.go`
- [CLI operations](https://github.com/ory/hydra/blob/master/cmd/cmd_perform.go): `cmd/cmd_perform.go`

### Keys and persistence

- [Signing key manager](https://github.com/ory/hydra/blob/master/jwk/manager.go): `jwk/manager.go`
- [Hardware key manager](https://github.com/ory/hydra/blob/master/hsm/manager_hsm.go): `hsm/manager_hsm.go`
- [SQL persistence](https://github.com/ory/hydra/blob/master/persistence/sql/persister.go): `persistence/sql/persister.go`
- [Client storage and auth](https://github.com/ory/hydra/blob/master/client/manager.go): `client/manager.go`

### Other components

- **OAuth client / user agent**
- **Login and consent app**
- **Operator**

## Connections

- OAuth client / user agent → HTTP server routing: sends requests (evidence: `README.md`)
- HTTP server routing → OAuth endpoints: routes to (evidence: `cmd/server/handler.go`)
- OAuth endpoints → OAuth/OIDC engine: calls protocol (evidence: `oauth2/handler.go`)
- OAuth/OIDC engine → Login and consent orchestration: requests interaction (evidence: `README.md`)
- Login and consent orchestration → Login and consent app: redirects for decisions (evidence: `README.md`)
- Login and consent orchestration → Authorization flow state: manages flow state
- OAuth endpoints → OAuth client / user agent: redirects with result (evidence: `README.md`)
- OAuth client / user agent → OAuth endpoints: exchanges code (evidence: `README.md`)
- HTTP server routing → Device authorization: serves device flow
- HTTP server routing → Client management: routes to (evidence: `cmd/server/handler.go`)
- HTTP server routing → JWKS management: routes to (evidence: `cmd/server/handler.go`)
- HTTP server routing → Trusted JWT grants: routes to
- Operator → CLI operations: runs commands
- CLI operations → HTTP server routing: calls admin API
- HTTP server routing → Configuration and wiring: uses configuration (evidence: `cmd/server/handler.go`)
- OAuth endpoints → Signing key manager: uses signing keys
- Signing key manager → Hardware key manager: delegates key operations
- OAuth endpoints → SQL persistence: persists OAuth state
- Client management → Client storage and auth: manages clients
- Client storage and auth → SQL persistence: stores client records
