Auth Primitive — IAM Service

The IAM Service is the platform's identity and access management backbone. It is the sole issuer of JWTs, the only service that writes to user and role tables, and the source of truth for every permission check in the API Gateway. Every other service trusts the JWT; no other service manages authentication directly.

---

Responsibilities

Responsibility	Detail
Authentication	Email + password, OAuth providers, TOTP MFA, SSO (SAML 2.0 + OIDC federation)
Token issuance	JWT ES256 access tokens (15 min) + refresh tokens (7 days)
Authorisation	Role and permission management; gRPC ValidateToken for the Gateway
Tenant management	Tenant creation, blocking, hierarchy traversal, ownership transfer
OIDC Provider	Full OAuth 2.1 + OpenID Connect IdP for external apps and AI agents
Custom Claims	Module-registered claims injected into every user JWT at login

---

Technical Stack

Parameter	Value
Language	Go
Service path	services/iam/
Port	Internal — consumed by Gateway over gRPC
OpenAPI spec	services/iam/api/openapi.yaml (1 450 lines — largest spec in the platform)
gRPC proto	proto/platform/iam/v1/iam_service.proto
Database	PostgreSQL with two migration files (OAuth tables + RLS policies)
sqlc	services/iam/sqlc.yaml

---

13 Internal Packages

Package	Purpose
internal/auth	Login, register, token generation (JWT ES256)
internal/config	Environment-based configuration
internal/data	Data access abstractions
internal/handler	HTTP request handlers
internal/mfa	TOTP (pquerna/otp), 10 recovery codes
internal/middleware	IAM-specific middleware (request context, tracing)
internal/oauthapp	OAuth application management (client IDs, secrets, scopes)
internal/oidc	OIDC provider implementation (ory/fosite)
internal/provider	Pluggable auth adapters (Google, GitHub, MetaMask, SAML, …)
internal/rbac	Role-Based Access Control engine
internal/repository	PostgreSQL repositories generated by sqlc
internal/tenant	Multi-tenant logic, B2B2B hierarchy traversal
internal/user	User domain logic (profile, status, providers)

---

3 gRPC Services

The IAM service is consumed exclusively via gRPC by the API Gateway. REST calls from clients pass through the Gateway, which translates them to gRPC.

gRPC service	Key RPCs	Consumers
IamService	CreateUser, RetrieveUser, ListUsers, UpdateUser, DeleteUser	Gateway, Data Layer
AuthService	Login, Refresh, ValidateToken	Gateway (every authenticated request)
TenantHierarchyService	IsDescendant, GetTenantStatus	Gateway delegation middleware

ValidateToken is called on every single request that carries a Authorization: Bearer header. It verifies the ES256 signature, checks expiry, and returns the decoded claim set including roles[] and tenantId. The Gateway never decodes JWTs without an IAM verification pass.

---

35+ REST Endpoints

All REST endpoints are exposed through the API Gateway at https://api.septemcore.com/v1/. The IAM service never faces the public internet directly.

Group	Endpoints	Count
Core Auth	POST /auth/register, POST /auth/login, POST /auth/logout, POST /auth/refresh, GET /auth/me	5
MFA	POST /auth/mfa/enable, POST /auth/mfa/verify, POST /auth/mfa/disable, POST /auth/recovery, GET /auth/recovery-codes, POST /auth/recovery-codes/regenerate	6
Security flows	POST /auth/verify-email, POST /auth/request-verify-email, POST /auth/request-reset, POST /auth/reset-password, POST /auth/invite, POST /auth/accept-invite	6
OAuth Providers	GET /auth/providers, POST /auth/login/:providerId, GET /auth/callback/:providerId	3
Users	POST /users, GET /users, GET /users/:id, PATCH /users/:id, DELETE /users/:id, PATCH /users/:id/restore	6
User providers	GET /users/:id/providers, POST /users/:id/providers/:providerId, DELETE /users/:id/providers/:providerId	3
RBAC	POST /roles, GET /roles, GET /roles/:id, PATCH /roles/:id, DELETE /roles/:id, POST /users/:id/roles, DELETE /users/:id/roles/:roleId, GET /permissions	8
Multi-tenant	GET /auth/tenants, POST /auth/select-tenant, POST /auth/switch-tenant	3
Custom claims	GET /auth/claims, POST /auth/claims, DELETE /auth/claims/:name	3
OIDC	GET /.well-known/openid-configuration, GET /.well-known/jwks.json, GET /oauth/authorize, POST /oauth/token, GET /oauth/userinfo, POST /oauth/revoke, POST /oauth/introspect	7
SSO	GET /auth/sso/providers, POST /auth/sso/providers, PATCH /auth/sso/providers/:id, DELETE /auth/sso/providers/:id, GET /auth/sso/login/:id, POST /auth/sso/callback/:id, GET /auth/sso/metadata	7
Tenants	POST /tenants, GET /tenants, GET /tenants/:id, PATCH /tenants/:id, DELETE /tenants/:id, and action endpoints	10+

---

Security Characteristics

Property	Value
JWT algorithm	ES256 (ECDSA P-256)
Access token TTL	15 minutes
Refresh token TTL	7 days (per-tenant scoped — stolen token ≠ access to other tenants)
Password hashing	Argon2id — 64 MB memory, 1 iteration, 4 threads, 32-byte key (NIST 800-63B)
Minimum password length	12 characters
MFA	TOTP RFC 6238 (30-second window, 10 recovery codes, Argon2id-hashed)
Anti-enumeration	Constant-time responses on register, login, invite, and password reset
Refresh token rotation	Every refresh call issues a new refresh token; the previous is revoked
Session isolation	Refresh tokens are tenant-scoped

---

Pluggable Auth Adapters

The IAM service ships five adapter categories. Any adapter returns a UserIdentity struct — the kernel takes it from there (creates/finds user, assigns tenant, issues JWT):

Category	Examples
oauth	Google, Apple, GitHub
wallet	MetaMask, WalletConnect
social	Telegram, Discord
banking	BankID, Monobank, Sber ID
enterprise	Active Directory, LDAP, SAML 2.0, OIDC Federation
custom	Any future provider via the AuthProvider interface

---

SDK Quick Reference

import { useAuth } from '@platform/sdk-auth';

const { user, isLoading, login, logout, refresh } = useAuth();

Full authentication lifecycle, MFA, provider management, and role operations are documented in the following pages:

• Authentication Lifecycle — register, login, refresh, logout, token pair
• MFA — TOTP enable, verify, disable, recovery codes
• Providers — OAuth, SSO, provider linking
• RBAC — roles, permissions, SDK useRBAC()
• Security Flows — email verification, password reset, invites
• Tenant Management — multi-tenant login, tenant switching