REST API v1 Reference
Summary of core endpoints across Discovery, Enrollment, Authentication, Policy, Channels, Broadcasts, Hub, Search, and Admin Control Plane.
Key API Endpoints (/api/v1)
All protected endpoints require an Authorization: Bearer <access_token> header. Administrative endpoints under /api/v1/admin/* additionally enforce controlPlaneGuard (X-Madar-Control-Plane-Key when configured).
| Method & Path | Scope | Purpose |
|---|---|---|
| GET /.well-known/madar-workspace.json | Public | Workspace discovery, Ed25519 public key, domain verification & SSO list |
| POST /api/v1/enroll | Public (Signed Token) | Bind employee device Ed25519 public key using signed enrollment token |
| POST /api/v1/auth/login | Workspace | Authenticate with employee ID / email / phone, password, and optional TOTP |
| POST /api/v1/auth/sso/login | Workspace SSO | Authenticate via OIDC id_token, SAML 2.0 assertion, or LDAP bind |
| GET /api/v1/policy/me | Authenticated | Fetch signed Ed25519 JWS policy bundle for active user |
| POST /api/v1/broadcasts | BROADCASTER / ADMIN | Publish verified broadcast with optional quiz_ack |
| POST /api/v1/channels/:id/decisions | Authenticated | Record formal channel decision linked to source message |
| GET /api/v1/hub | Authenticated | Retrieve categorized Action Hub items (urgent broadcasts, follow-ups, decisions) |
| GET /api/v1/search?q=... | Authenticated | Unified orthographic Arabic search across authorized records |
| POST /v1/handles & POST /v1/wake | Blind Relay | Register 128-bit push handle and dispatch zero-payload wake signal |