Skip to main content
Ory Kratos is a headless, API-first identity and authentication system built for cloud-native environments. This page explains the system architecture and core components.

​
API-first design

Kratos follows an API-first approach with two distinct API surfaces:

​
Public API

The public API handles end-user interactions through self-service flows:
  • Self-service flows - Registration, login, recovery, verification, and settings
  • Session management - Session creation, validation, and revocation via the /sessions/whoami endpoint
  • Browser and API clients - Supports both traditional web applications and native/SPA clients

​
Admin API

The admin API provides privileged operations for identity management:
  • Identity CRUD - Create, read, update, and delete identities
  • Identity import - Batch import identities from external systems
  • Credential management - Manage user credentials directly
  • Administrative queries - List and search identities
The admin API should never be exposed to end users. Always place it behind authentication and authorization layers.

​
Core components

Kratos is built on a modular registry-based architecture defined in driver/registry.go:49:

​
Registry

The central dependency injection container that provides access to all system components: 
type Registry interface {
    Init(ctx context.Context, ctxer contextx.Contextualizer, opts ...RegistryOption) error
    
    // Configuration
    config.Provider
    
    // Persistence layer
    persistence.Provider
    
    // Identity management
    identity.HandlerProvider
    identity.ManagementProvider
    identity.PoolProvider
    
    // Session management
    session.HandlerProvider
    session.ManagementProvider
    session.PersistenceProvider
    
    // Self-service flows
    login.FlowPersistenceProvider
    registration.FlowPersistenceProvider
    recovery.FlowPersistenceProvider
    verification.FlowPersistenceProvider
    settings.FlowPersistenceProvider
    
    // And many more...
}

​
Identity pool

Manages identity storage and retrieval with multi-tenancy support through Network IDs (NID).

​
Session manager

Handles session lifecycle, token generation, and validation. Sessions are stored in the database and referenced via session tokens.

​
Flow managers

Each self-service operation (login, registration, etc.) has a dedicated flow manager that orchestrates:
  • Flow initialization
  • State transitions
  • Strategy execution
  • UI rendering
  • Error handling

​
Strategy system

Kratos uses a strategy pattern for authentication methods. Each credential type (password, OIDC, WebAuthn, etc.) implements strategy interfaces for different flows.

​
Database layer

Kratos requires a persistent database for storing:
  • Identities - User accounts and profile data
  • Credentials - Authentication credentials (hashed passwords, OIDC connections, etc.)
  • Sessions - Active user sessions
  • Flow state - In-progress self-service flows
  • Verification and recovery tokens - Temporary codes and links
Supported databases: PostgreSQL, MySQL, CockroachDB, and SQLite (development only)

​
Multi-tenancy

Kratos supports multi-tenancy through Network IDs (NIDs). Each identity, session, and flow belongs to a specific network, enabling isolation in shared deployments. 
type Identity struct {
    ID             uuid.UUID `json:"id" db:"id"`
    NID            uuid.UUID `json:"-" db:"nid"`
    OrganizationID uuid.NullUUID `json:"organization_id,omitempty" db:"organization_id"`
    // ...
}

​
Security architecture

​
CSRF protection

Browser flows include CSRF tokens to prevent cross-site request forgery attacks. The token is embedded in forms and validated on submission.

​
Encryption

Sensitive credential data (like OIDC tokens) is encrypted at rest using the cipher provider: 
type Provider interface {
    Cipher(ctx context.Context) cipher.Cipher
}

​
Password hashing

Passwords are hashed using Argon2id by default, with configurable parameters for security/performance tuning.

​
Flow-based architecture

All user-facing operations follow a flow-based pattern:
  1. Flow initialization - Client requests a new flow
  2. UI rendering - Kratos returns a UI container with form fields
  3. User interaction - User submits data
  4. Validation and processing - Kratos validates and processes the submission
  5. State transition - Flow moves to next state or completes
  1. Client calls GET /self-service/login/browser or POST /self-service/login/api
  2. Kratos creates a flow with state choose_method
  3. UI renders available login methods (password, OIDC, etc.)
  4. User submits credentials to POST /self-service/login?flow=<id>
  5. Kratos validates credentials and creates a session
  6. Flow transitions to success state
  7. Session token is issued

​
Deployment patterns

​
Standalone deployment

Kratos runs as a single service with separate public and admin ports: 
serve:
  public:
    port: 4433
  admin:
    port: 4434

​
With reverse proxy

Common production setup with a reverse proxy handling TLS and routing: 
[Browser] → [Reverse Proxy] → [Kratos Public API]
                            → [UI Application]
[Admin Tools] → [Reverse Proxy] → [Kratos Admin API]

​
With Ory Hydra

Kratos can act as an identity provider for OAuth2/OIDC flows when integrated with Ory Hydra.
Never expose the admin API to the public internet. Use network policies or authentication to restrict access.

​
Configuration

Kratos is configured via YAML files or environment variables. The configuration provider (driver/config/config.go) handles:
  • Flow lifespans and URLs
  • Enabled authentication strategies
  • Database connection settings
  • Email/SMS delivery settings
  • Security parameters
  • Multi-tenancy settings

​
Extensibility

Kratos supports extensibility through:
  • Webhooks - Call external services during flows (e.g., password migration hooks)
  • Custom identity schemas - Define custom user attributes via JSON Schema
  • Strategy registration - Add custom authentication strategies
  • Hooks - Execute custom logic before/after flow completion
See driver/registry.go:233 for the strategy registration interface.

Build docs developers (and LLMs) love

Get started for freeTalk to us