# TAJMAC Auth — AI Integration Guide

## What is TAJMAC Auth?
TAJMAC Auth is a self-hosted identity platform providing complete authentication infrastructure.

- REST API server on port 3002 (Hono / Bun)
- Admin portal on port 3003 (Next.js)
- Hosted login UI on port 3004 (Next.js)
- Database: PostgreSQL with schema `tajmac_auth`

## Key API endpoints

### Authentication (public)

POST /api/v1/auth/sign-in/email
Body: { email, password, appSlug }
Response: sets tajmac.session HttpOnly cookie

POST /api/v1/auth/sign-up/email
Body: { email, password, name, appSlug }

GET /api/v1/auth/session
Cookie: tajmac.session=<token>
Response: { user: { id, email, name, emailVerified }, session: { id, expiresAt } }

POST /api/v1/auth/sign-out
Cookie: tajmac.session=<token>

POST /api/v1/auth/magic-link/send
Body: { email, appSlug }

POST /api/v1/auth/forgot-password
Body: { email, appSlug }

POST /api/v1/auth/reset-password
Body: { token, password }

### Portal management (requires portal admin session)

GET    /api/v1/portal/apps
POST   /api/v1/portal/apps
GET    /api/v1/portal/apps/:slug
PATCH  /api/v1/portal/apps/:slug
DELETE /api/v1/portal/apps/:slug
GET    /api/v1/portal/admin/users
GET    /api/v1/portal/admin/stats
GET    /api/v1/portal/organizations
POST   /api/v1/portal/organizations
GET    /api/v1/portal/permissions/roles
POST   /api/v1/portal/permissions/check
GET    /api/v1/portal/admin/flags
POST   /api/v1/portal/admin/flags
GET    /api/v1/portal/admin/api-keys
POST   /api/v1/portal/admin/api-keys

### OIDC Provider

GET /.well-known/openid-configuration
GET /.well-known/jwks.json
GET /oidc/auth
POST /oidc/token
GET /oidc/me

## Session validation (server-side)

const sessionToken = req.cookies.get("tajmac.session")?.value;
const res = await fetch(`${process.env.TAJMAC_AUTH_URL}/api/v1/auth/session`, {
  headers: { Cookie: `tajmac.session=${sessionToken}` },
});
const { user } = await res.json();

## Environment variables

TAJMAC_AUTH_URL=http://localhost:3002
TAJMAC_APP_SLUG=my-app

## Important notes

1. Session cookie is HttpOnly — use server-side validation only.
2. Each sign-in request MUST include the correct appSlug.
3. The portal app slug is "portal" — do not use for your application.
4. Sessions use 256-bit random tokens (not JWTs).
5. For API automation, use API keys (Portal > API Keys).