# Identity & Access Service

سرویس احراز هویت و دسترسی — SSO مرکزی با Keycloak.

Canonical contracts: [`docs/reference/services-contracts.md`](../../../docs/reference/services-contracts.md) §8  
Architecture: [`docs/architecture/identity-architecture.md`](../../../docs/architecture/identity-architecture.md)  
Registry: [`docs/module-registry.md`](../../../docs/module-registry.md#identity-access)

## Responsibilities

- User profile + identity-layer tenant membership
- OIDC config for frontend
- Authorization code → token (BFF)
- Mobile OTP start/complete + session handoff redeem
- Keycloak Admin sync

## Database

`identity_access_db` (database-per-service; not Core)

> Operational workspace roles live in Core `tenant_memberships` — see [ADR-007](../../../docs/architecture/adr/ADR-007.md).

## Main APIs

| Method | Path | Notes |
| --- | --- | --- |
| GET | `/health` | Public |
| GET | `/api/v1/auth/config` | OIDC config |
| GET | `/api/v1/auth/login-url` | Login redirect helper |
| POST | `/api/v1/auth/token` | Code exchange |
| GET | `/api/v1/auth/me` | Current user |
| POST | `/api/v1/auth/mobile/start` | Unified mobile start |
| POST | `/api/v1/auth/mobile/complete` | Unified mobile complete |
| POST | `/api/v1/auth/session/redeem` | Handoff redeem |
| POST | `/api/v1/auth/mobile/request` | SSO user mobile verify request |
| POST | `/api/v1/auth/mobile/verify` | SSO user mobile verify |
| POST | `/api/v1/auth/register*` | Legacy register flows |
| POST | `/api/v1/users` | platform_admin |
| POST/GET | `/api/v1/tenants/{id}/members` | platform_admin |

Full table: services-contracts §8.

## Run

```bash
cd backend/services/identity-access
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8001
```

## Test

```bash
pytest -q
```