‹ Back to docs
Auth Guide
Integrating ORIS Identity
Every product authenticates through ORIS Identity. No exceptions. This guide covers the complete integration.
Quick Start
npm install @oris/auth-client
// In your middleware or route guard:
import { validateOrisJwt, extractToken } from '@oris/auth-client';
const token = extractToken(req.headers.authorization, req.cookies);
const claims = await validateOrisJwt(token, {
issuer: 'https://auth.meetoris.com',
});
// claims.sub → user ID
// claims.tenant_id → org partition key
// claims.roles → { "DE": "ngo_admin", "KAP": "viewer" }
// claims.ai_tier → "starter" | "pro" | "enterprise"JWT Claims Reference
subUUIDStable user ID across all productstenant_idUUIDOrganisation partition keytenant_slugstringHuman-readable org identifier (e.g. "acme-consulting")emailstringVerified user emailproductsstring[]Licensed product codes: ["DE","KAP","WAS"]rolesRecordPer-product role map: {"DE":"ngo_admin","KAP":"viewer"}ai_tierenumstarter | pro | enterprise — drives model routingdata_residencyenumIN | EU | US — governs provider selection for PIIcross_vertical_accessbooleanWhether cross-vertical queries are permittedcross_vertical_scopesstring[]Allowed target verticals for cross queriesjtistringJWT ID for revocation trackingRBAC & Permissions
Roles are assigned per-product per-tenant. A user can be admin in Donateazy and viewer in Kapitalyze. Check roles from JWT claims — never query a local permissions table.
LOSadmin, accountant, viewerPOShr_admin, payroll_manager, employee, viewerROSowner, manager, staffKAPadvisor, client, viewerDEngo_admin, fundraiser, donor_managerWASowner, executor, viewerCTRadmin, legal, signatory, viewerOOSsuper_admin, admin, memberM2M Authentication
Background jobs and inter-service calls use Product API Keys instead of user JWTs. Keys are created via POST /m2m/keys (requires OOS admin). Use client_credentials grant to exchange for a service JWT.
POST /token
{
"grant_type": "client_credentials",
"client_id": "donateazy-worker",
"client_secret": "oris_m2m_..."
}Session Management
Access tokens: 1-hour TTL, httpOnly secure cookie. Refresh tokens: 7 days, rotated on use. Logout from any product calls POST /logout which revokes all sessions ecosystem-wide. Token revocation is tracked via Redis jti list with sub-millisecond lookup.