Integration patterns

IdentSphere works with any language. The Rust + TypeScript packages are the fastest path, but they are not the only path.

Two patterns, pick one

Pattern 1 — Sidecar service (recommended for non-Rust stacks)

Run identsphere-server as a Docker container alongside your application. Your application calls IdentSphere over HTTP for auth operations.

┌─────────────────────────┐         ┌─────────────────────────┐
│  Your application       │         │  identsphere-server           │
│  (Python / Go / etc.)   │ ◄──REST─►│  (Rust binary)          │
└────────────┬────────────┘         └────────────┬────────────┘
             │                                    │
             ▼                                    ▼
   ┌─────────────────────┐              ┌─────────────────────┐
   │ Your app database   │              │ IdentSphere schema        │
   │ (your tables)       │              │ (auth tables)       │
   └─────────────────────┘              └─────────────────────┘
              (same Postgres or different — your choice)

Best for: Python, Go, Ruby, PHP, Java, .NET — anything not Rust.

Pros: language-agnostic, zero auth code in your app, isolated upgrades.

Cons: extra service to deploy, +1 network hop (typically <2ms over localhost).

Pattern 2 — JWT validation only

IdentSphere issues standard RS256 JWTs. Your application validates them using any JWT library in your language. IdentSphere still handles login / signup / all the user flows; your app just trusts the resulting tokens.

┌─────────────────────────┐                ┌─────────────────────────┐
│  Your application       │                │  identsphere-server           │
│  validates JWTs against │ ◄─JWKS fetch───┤  publishes /jwks.json   │
│  /.well-known/jwks.json │                └─────────────────────────┘
└─────────────────────────┘

Best for: high-traffic services that don't want a round-trip per request — validation is local.

Pros: no extra service call per request, fully decoupled.

Cons: revocation has a propagation lag of (cache TTL + access token TTL).

Decision matrix

You have	Use Pattern...	Why
Rust + Axum	(neither — use identsphere-axum directly as a crate)	Native integration, all hooks available
TypeScript / React	(use @identsphere/react)	Typed hooks, refresh, CSRF — all handled
Python / Django / FastAPI	Pattern 1	Sidecar + a small DRF/FastAPI wrapper; pure REST
Go	Pattern 2 (JWT validation)	High-throughput services; revocation lag acceptable
Node (non-React)	Pattern 1 or 2	Both work; depends on framework
Ruby on Rails	Pattern 1	Sidecar; ruby-jwt for validation if needed
Java / Kotlin (Spring)	Pattern 1 or 2	Spring Security's resource-server adapter handles JWKS natively
PHP (Laravel / Symfony)	Pattern 1	Sidecar; firebase/php-jwt for validation
Multi-language microservices	Pattern 1 for writes, Pattern 2 for reads	identsphere-server is the single source of truth; services validate JWTs locally

What is the same regardless of pattern

• The HTTP contract. ~40 endpoints, documented in the API reference.
• The token format. Standard RS256 JWTs with documented claims.
• The cookie format. identsphere_at, identsphere_rt, identsphere_csrf — standard cookies, browsers handle them.
• The data model. users, organizations, organization_memberships in your Postgres, documented in Schema. Your application can JOIN against these tables directly.

Specific language guides

• Rust (Axum) — native crate integration
• TypeScript / React — typed hooks
• Python — FastAPI + httpx + pyjwt
• Node.js (non-React) — Express + jose
• Go — chi + golang-jwt
• Ruby — Rails + ruby-jwt
• Java / Kotlin — Spring Security
• PHP — Laravel / Symfony + firebase/php-jwt
• Any language (raw REST) — curl-equivalent calls