API overview

API overview (Orchestrator)

Audience: backend, frontend, qa
Status: specced
Owns: backend
Depends on: Orchestrator overview, Backend stack, CAP Auth module, Architecture handover

Contract rule

OpenAPI is the HTTP source of truth for Orchestrator REST. Implementation SoT is elimi-ecosystem/apps/orchestrator/openapi/openapi.yaml. The workspace-root orchestrator-openapi.yaml is kept in lockstep (35 operations); the docs site publishes a synced copy. Clients must not reverse-engineer screens or tickets for endpoints.

Identity verification and payment initiation are gRPC only (@yourorg/proto) — not public REST.

Artifact location

Item	Path
Design SoT	`orchestrator-openapi.yaml` (ecosystem root)
Published copy	`openapi/orchestrator.yaml` in elimi-documentation
Interactive	Scalar — Orchestrator REST
gRPC	Contracts — gRPC (`VerifyIdentity`, `ProvisionAccount`, `InitiatePayment`)
Gateway prefix	`/v1/ol`
Staging	`www.staging-api.elimi-ecosystem.e-limi.africa`
Production	`api.elimi-ecosystem.e-limi.africa`

Resource groups

Group	Use cases	Notes
Auth	Register (with `intents[]`), OTP resend, Google, login, verify-account, forgot/reset password, refresh, logout, change-password, delete-account	Issues JWT; OTP delivery via Notifications; JWKS for local validation. `User.mustChangePassword` after `ProvisionAccount` (generated password). Delete deactivates login and emits `user.deleted`. Onboarding hats live on CAP.
Payments (HTTP)	Paystack webhook; verify by reference	Initiate is gRPC from CAP/LMS — Payment architecture
Storage	Upload, signed upload-url, confirm, resolve, delete asset	Signed URLs; sensitive assets resolve-on-access
Notifications	List, unread count, mark read / read-all, delete, GET/PUT preferences	User-scoped inbox; channel prefs skip email/in_app/sms except auth OTP / password-reset / provisioned-password. Send path is `notification.requested` or in-process `dispatch`
Conversations	Create thread, list, poll/post messages	Any authenticated user; `platform` query like notifications. Optional `notify.channels` clamped by policy (`in_app` on; email/SMS off unless enabled). Replies do not email/SMS by default. Poll in v1; WebSocket later on the same resources
Banks	List supported banks by country; resolve registered account name	List is Paystack-backed (cached 24 h, public). `POST /banks/resolve` is JWT-only: Paystack Resolve Account Number with Redis HMAC cache (name only, 12 h hit / 60 s miss)
Address	Countries, states, LGAs	Reference data for onboarding forms

Auth flow (sequence)

sequenceDiagram
  participant C as Client
  participant A as Auth
  participant N as Notifications
  participant M as Mail provider
  C->>A: POST /auth/register (intents)
  A->>A: Create user pending verify
  A->>N: send OTP email
  N->>M: Deliver mail
  C->>A: POST /auth/verify-account
  A->>C: JWT
  A-->>A: outbox user.created
  Note over C: CAP validates JWT via JWKS; provisions cap_users

Google sign-in skips OTP verify but still returns the same JWT shape. Register intents[] drives which platforms receive provisioning events.

ProvisionAccount (gRPC, not REST): CAP POST /centre/staff calls OL to get-or-create a User by email. New users get a generated password mailed in-process (never on notification.requested) and mustChangePassword: true on later login. Existing users get no new password. user.created still fires when a User is first created; CAP must not mint OL user ids.

Security

Public: register, OTP resend, verify-account, login, Google, forgot-password, reset-password, list banks
Bearer JWT: refresh, logout, change-password, delete-account, notifications (incl. preferences), conversations, storage (user-owned), payment verify, resolve bank account name
Storage resolve (POST /storage/resolve): user JWT or internal X-Elimi-Service-Key (ORCHESTRATOR_SERVICE_API_KEY, same value on CAP). Other storage routes stay JWT-only. Browsers must not send the service key.
Webhook: Paystack (signature verification; not bearer)
Service callers for internal notify may use API key / mTLS later (securitySchemes in OpenAPI)