kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
197 lines
3.3 KiB
Markdown
197 lines
3.3 KiB
Markdown
# Endpoints: Auth
|
|
|
|
Session and user preference endpoints for Gishen-B2B demo login and future production auth.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
**Entity:** [`../entities/session-user.md`](../entities/session-user.md)
|
|
|
|
---
|
|
|
|
## POST /v1/auth/login
|
|
|
|
Demo role selector login (mock phase).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Public |
|
|
| **Roles** | — |
|
|
|
|
### Request
|
|
|
|
```json
|
|
{
|
|
"demo_role": "HR_ADMIN",
|
|
"locale": "en"
|
|
}
|
|
```
|
|
|
|
`demo_role`: `SUPER_USER` \| `HR_ADMIN` \| `FINANCE` \| `MEMBER`
|
|
|
|
Production (future): `{ "email", "password" }` or OAuth code exchange.
|
|
|
|
### Response 200
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"token": "mock_jwt_...",
|
|
"user": {
|
|
"id": "usr_01HHR",
|
|
"email": "hr.demo@acme.et",
|
|
"full_name": "Demo HR Admin",
|
|
"org_id": "org_01DEMO",
|
|
"roles": ["HR_ADMIN"],
|
|
"locale": "en",
|
|
"org_status": "active",
|
|
"permissions": ["org:read", "org:write_hr", "members:write", "packages:write", "migration:write", "finance:read"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `VALIDATION_FAILED` | 400 | Invalid `demo_role` |
|
|
| `UNAUTHENTICATED` | 401 | Production bad credentials |
|
|
|
|
### Clinical withhold
|
|
|
|
N/A — session only.
|
|
|
|
---
|
|
|
|
## POST /v1/auth/logout
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | Any |
|
|
|
|
### Response 204
|
|
|
|
No body.
|
|
|
|
---
|
|
|
|
## GET /v1/auth/me
|
|
|
|
Current session user.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | Any |
|
|
|
|
### Response 200
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"id": "usr_01HMEM",
|
|
"email": "member.demo@acme.et",
|
|
"full_name": "Demo Member",
|
|
"org_id": "org_01DEMO",
|
|
"member_id": "mbr_01DEMO",
|
|
"customer_id": "cus_01DEMO",
|
|
"roles": ["MEMBER"],
|
|
"locale": "am",
|
|
"org_status": "active",
|
|
"allowance_summary": {
|
|
"allowance_remaining": { "amount": "10800.00", "currency": "ETB" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP |
|
|
|------|------|
|
|
| `UNAUTHENTICATED` | 401 |
|
|
|
|
---
|
|
|
|
## PATCH /v1/auth/me/locale
|
|
|
|
Update user locale preference.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | Any |
|
|
|
|
### Request
|
|
|
|
```json
|
|
{ "locale": "am" }
|
|
```
|
|
|
|
### Response 200
|
|
|
|
Returns updated session user with `locale: "am"`.
|
|
|
|
### Validation
|
|
|
|
| Rule | Code |
|
|
|------|------|
|
|
| `locale` in `en`, `am` | `VALIDATION_FAILED` |
|
|
|
|
### Clinical withhold
|
|
|
|
N/A.
|
|
|
|
---
|
|
|
|
## GET /v1/auth/demo-profiles
|
|
|
|
List pre-seeded demo personas for `/login` selector.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Public |
|
|
| **Roles** | — |
|
|
|
|
### Response 200
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"demo_role": "SUPER_USER",
|
|
"label": "Super User",
|
|
"description": "Full portal access including clinical detail"
|
|
},
|
|
{
|
|
"demo_role": "HR_ADMIN",
|
|
"label": "HR Administrator",
|
|
"description": "Members, departments, packages — no clinical detail"
|
|
},
|
|
{
|
|
"demo_role": "FINANCE",
|
|
"label": "Finance Approver",
|
|
"description": "Spend, statements, approvals — no clinical detail"
|
|
},
|
|
{
|
|
"demo_role": "MEMBER",
|
|
"label": "Member",
|
|
"description": "Own allowance, orders, prescriptions"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## UI routes
|
|
|
|
| Route | Purpose |
|
|
|-------|---------|
|
|
| `/login` | Demo role selector + locale switcher |
|
|
|
|
## Clinical withhold notes
|
|
|
|
Auth endpoints do not expose clinical data. Role list on session determines withhold behavior on downstream endpoints.
|