API & Functional Specification
Functional expectations and API contract checklist for OpenVals: user flows mapped to API groups, validations, authorization, and failure behavior. Reconcile listed paths with live FastAPI routers and OpenAPI before integration.
Related: End-to-End User Flow · Platform Architecture Flow
Source specifications: End-to-End User Flow (.docx) · API & Functional Specification (.docx) · Platform Architecture Flow (.docx)
API design principles
- Consistent `/api/v1` base path unless routing specifies otherwise.
- Authenticate protected routes; authorize every operation server-side.
- Derive tenant context from the authenticated session, not an untrusted organization ID alone.
- Validate bodies, query params, identifiers, amounts, and state transitions.
- Return consistent machine-readable error codes and user-safe messages.
- Use idempotency keys for payment creation, reconciliation, webhooks, and retryable writes.
- Document pagination, sorting, filtering, and response schemas for list endpoints.
Authentication and account APIs
| Operation | Endpoint | Auth | Key validations / behavior |
|---|---|---|---|
| Signup | POST /auth/signup | Public | Validate fields; reject duplicate email; transactional tenant/owner/trial |
| Login | POST /auth/login | Public | Validate credentials; issue session |
| Current user | GET /auth/me | Authenticated | User, org context, roles, permissions |
| Forgot password | POST /auth/forgot-password | Public | Generic response; rate limit; 30-minute token |
| Reset password | POST /auth/reset-password | Reset token | Validate token; revoke all sessions |
| Refresh / Logout | Confirm implemented routes | Session | Rotate refresh; revoke on logout |
Organization, invitation, and membership APIs
| Operation | Route family | Auth | Key validations / behavior |
|---|---|---|---|
| Invite member | /organization/.../invitations | Owner / admin | Email, role, org status, seat availability |
| Accept invitation | /accept-invite flow | Invitation token | Token, expiry, seats; no duplicate membership |
| Manage team | Organization user routes | Org role | Tenant scope; validate role changes |
| Seat change | POST/PATCH /organization/billing/seats | Billing permission | Plan limits, proration, seat usage |
Plans, subscriptions, and billing APIs
| Operation | Endpoint | Auth | Key validations / behavior |
|---|---|---|---|
| Plan catalog | Plan route (confirm) | Policy-dependent | Visible/purchasable plans and prices |
| Checkout | POST /organization/billing/checkout | Billing permission | Plan, interval, eligibility, idempotency |
| Razorpay verification | POST /organization/billing/razorpay/verify | Auth / provider | Signature, IDs, amount, status |
| Cancel / Resume | Billing cancel/resume routes | Billing permission | Validate state and timing |
| Provider webhook | POST /webhooks/{provider} | Provider signature | Verify, dedupe, reconcile safely |
Invoice and payment APIs
| Operation | Endpoint | Auth | Key validations / behavior |
|---|---|---|---|
| Create / issue invoice | Admin invoice routes | Platform invoice permission | Line items, due days, draft→issued workflow |
| Public invoice view | Public GET route | Public token/link | Minimum fields; validate status |
| Pay invoice | /public/invoices/{id}/pay | Payment context | Payable state, balance, idempotency |
| Mark offline paid | Admin invoice route | Platform payment permission | Reference, amount, audit |
| Reconciliation | Internal mark_invoice_paid | Internal | Idempotent; subscription + entitlements |
Admin Console APIs
| Area | Route family | Required authorization |
|---|---|---|
| Overview | GET /admin/overview | Platform overview permission |
| Organizations | /admin/organizations | Platform organization permissions |
| Users | /admin/users | Platform user permissions |
| Subscriptions | /admin/subscriptions | Platform subscription permissions |
| Invoices | /admin/invoices | Platform invoice permissions |
| Audit | GET /admin/audit | Platform audit permission |
| Plans / roles / deliveries | Confirm /admin/plans, roles, deliveries | Platform access-management permissions |
Validation and authorization matrix
| Validation | Expected behavior |
|---|---|
| Missing authentication | 401 Unauthorized |
| Expired or invalid session | 401 Unauthorized |
| Insufficient permission | 403 Forbidden |
| Organization-only account in Admin Console | 403 Forbidden |
| Seat capacity exceeded | 402 with code SEAT_LIMIT_EXCEEDED |
| Invalid body or field | 400 or 422 |
| Duplicate resource | 409 Conflict where appropriate |
| Invalid invitation/reset token | Reject without state change |
| Invalid payment signature | Reject; do not activate subscription |
| Duplicate webhook / retry | Idempotent result |
| Unpaid subscription write | Block per entitlement policy |
Recommended response shape
Illustrative success envelope—align field names with the implemented API:
{
"success": true,
"data": {},
"message": "Operation completed",
"request_id": "correlation-id"
}Illustrative error response:
{
"success": false,
"error": {
"code": "SEAT_LIMIT_EXCEEDED",
"message": "The organization has reached its seat limit."
},
"request_id": "correlation-id"
}Functional rules by domain
Authentication: no password hashes in responses; rate-limit login and reset; generic forgot-password responses; revoke sessions on reset; separate platform vs organization authorization.
Subscription and entitlements: centralize transitions; backend entitlement mode; validate seats on writes; never activate from browser redirect alone; idempotent reconciliation.
Invoices and payments: server-side totals; validate currency, balance, references; verify provider signatures; transactional updates; reactivate only eligible subscriptions.
Admin and audit: explicit platform permission per action; record actor, target, action, timestamp, correlation ID, before/after values; do not rely on frontend route guards alone.
Non-functional requirements
| Area | Requirement |
|---|---|
| Security | TLS, secure cookies, CSRF, secrets, least privilege, tenant isolation |
| Reliability | Transactions, idempotency, bounded retries, safe webhook replay |
| Performance | Pagination; indexed tenant columns; avoid unbounded responses |
| Observability | Structured logs, correlation IDs, payment/worker/email/auth metrics |
| Data integrity | Foreign keys, uniqueness, consistent transitions, auditable mutations |
| API documentation | OpenAPI schemas, auth requirements, examples, error catalogue |
API test checklist
- Signup validation, duplicate email, transactional tenant creation, trial defaults
- Login success/failure, session expiry, refresh and logout
- Organization role versus platform permission enforcement
- Invitation token expiry, reuse, duplicate membership, seat limit
- Checkout, invalid signature, duplicate webhook, failed payment
- Cancel/resume/seat change edge cases
- Invoice draft, issue, public access, online and offline reconciliation
- Subscription transition and entitlement enforcement for every state
- Admin permission checks and audit event creation
- Password reset expiry, single use, generic response, session revocation
- Pagination, filtering, validation errors, rate limits, correlation IDs
Contract confirmation required
This catalogue is a functional baseline. Before frontend integration, compare with FastAPI routers and OpenAPI output: HTTP methods, payloads, response fields, status codes, permission identifiers, pagination, and webhook paths.