Integration patterns

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

note

The core model is the same one every major auth provider uses: IdentSphere is a service, and your backend authorizes each request by validating the RS256 access token locally against the cached JWKS — no network hop per request, in any language. For the per-language verifier snippets and the full picture, see Validating tokens in your backend.

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 — Local JWT validation (the standard model)

IdentSphere issues standard RS256 JWTs. Your application validates them using any JWT library in your language, locally against the cached JWKS. IdentSphere still handles login / signup / all the user flows; your app just trusts the resulting tokens on the per-request hot path. This is how Auth0, Clerk, Keycloak, Supabase GoTrue, Ory, and SuperTokens all expect backends to authorize requests — see Validating tokens in your backend for the per-language snippets.

┌─────────────────────────┐                ┌─────────────────────────┐
│  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

Every language page has a Verify tokens in your backend section showing the local-JWKS validation snippet for that language. The cross-language overview is Validating tokens in your backend.

• 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