OpenVals
4. Use the platform

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

OperationEndpointAuthKey validations / behavior
SignupPOST /auth/signupPublicValidate fields; reject duplicate email; transactional tenant/owner/trial
LoginPOST /auth/loginPublicValidate credentials; issue session
Current userGET /auth/meAuthenticatedUser, org context, roles, permissions
Forgot passwordPOST /auth/forgot-passwordPublicGeneric response; rate limit; 30-minute token
Reset passwordPOST /auth/reset-passwordReset tokenValidate token; revoke all sessions
Refresh / LogoutConfirm implemented routesSessionRotate refresh; revoke on logout

Organization, invitation, and membership APIs

OperationRoute familyAuthKey validations / behavior
Invite member/organization/.../invitationsOwner / adminEmail, role, org status, seat availability
Accept invitation/accept-invite flowInvitation tokenToken, expiry, seats; no duplicate membership
Manage teamOrganization user routesOrg roleTenant scope; validate role changes
Seat changePOST/PATCH /organization/billing/seatsBilling permissionPlan limits, proration, seat usage

Plans, subscriptions, and billing APIs

OperationEndpointAuthKey validations / behavior
Plan catalogPlan route (confirm)Policy-dependentVisible/purchasable plans and prices
CheckoutPOST /organization/billing/checkoutBilling permissionPlan, interval, eligibility, idempotency
Razorpay verificationPOST /organization/billing/razorpay/verifyAuth / providerSignature, IDs, amount, status
Cancel / ResumeBilling cancel/resume routesBilling permissionValidate state and timing
Provider webhookPOST /webhooks/{provider}Provider signatureVerify, dedupe, reconcile safely

Invoice and payment APIs

OperationEndpointAuthKey validations / behavior
Create / issue invoiceAdmin invoice routesPlatform invoice permissionLine items, due days, draft→issued workflow
Public invoice viewPublic GET routePublic token/linkMinimum fields; validate status
Pay invoice/public/invoices/{id}/payPayment contextPayable state, balance, idempotency
Mark offline paidAdmin invoice routePlatform payment permissionReference, amount, audit
ReconciliationInternal mark_invoice_paidInternalIdempotent; subscription + entitlements

Admin Console APIs

AreaRoute familyRequired authorization
OverviewGET /admin/overviewPlatform overview permission
Organizations/admin/organizationsPlatform organization permissions
Users/admin/usersPlatform user permissions
Subscriptions/admin/subscriptionsPlatform subscription permissions
Invoices/admin/invoicesPlatform invoice permissions
AuditGET /admin/auditPlatform audit permission
Plans / roles / deliveriesConfirm /admin/plans, roles, deliveriesPlatform access-management permissions

Validation and authorization matrix

ValidationExpected behavior
Missing authentication401 Unauthorized
Expired or invalid session401 Unauthorized
Insufficient permission403 Forbidden
Organization-only account in Admin Console403 Forbidden
Seat capacity exceeded402 with code SEAT_LIMIT_EXCEEDED
Invalid body or field400 or 422
Duplicate resource409 Conflict where appropriate
Invalid invitation/reset tokenReject without state change
Invalid payment signatureReject; do not activate subscription
Duplicate webhook / retryIdempotent result
Unpaid subscription writeBlock per entitlement policy

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

AreaRequirement
SecurityTLS, secure cookies, CSRF, secrets, least privilege, tenant isolation
ReliabilityTransactions, idempotency, bounded retries, safe webhook replay
PerformancePagination; indexed tenant columns; avoid unbounded responses
ObservabilityStructured logs, correlation IDs, payment/worker/email/auth metrics
Data integrityForeign keys, uniqueness, consistent transitions, auditable mutations
API documentationOpenAPI 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.