Integration guides

Build against FVI

These guides cover everything you need to integrate with the Falcon Veritas API in production, following the same standards that back the OpenAPI 3.1 spec at /api/public/openapi.yaml.

1. Authentication

FVI uses OAuth 2.0 Bearer tokens (RFC 6750). Tokens are Supabase-issued JWTs obtained through the sign-in flow (email/password, magic link, or your configured enterprise SSO — SAML 2.0 or OIDC). Every request MUST send the token in theAuthorization header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens are scoped by tenant and by role (viewer, analyst, admin, platform_admin). Access is enforced twice — in the server function middleware and again at the database via Postgres RLS. A missing or expired token returns 401; a token that lacks the required role returns 403.

2. Requests & responses

All requests use JSON (application/json; charset=utf-8). Timestamps are ISO-8601 in UTC (2026-07-05T14:22:19Z). IDs are UUID v4. Money is returned as a decimal string plus an ISO-4217 currency code — never a float.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-07-05T14:22:19Z",
  "amount": "1250.00",
  "currency": "USD"
}

3. Error model (RFC 7807)

Errors follow RFC 7807 problem+json. Every error response carries a stable type URI, HTTP status, human-readable title, and a request_id you can quote when contacting support.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type":     "https://app-fvi.falconveritas.com/errors/validation",
  "title":    "Validation failed",
  "status":   422,
  "detail":   "amount must be a positive decimal",
  "instance": "/api/reconciliation/batches",
  "request_id": "req_01JB3QK6H3Q0M8W2S4X7Y9Z1AB",
  "errors": [ { "field": "amount", "code": "positive_decimal" } ]
}

4. Pagination

List endpoints use cursor pagination for stable ordering and O(1) performance. The next page cursor is opaque — treat it as a string and pass it back verbatim in ?cursor=. The Link header (RFC 8288) mirrors the same information for HTTP-native clients.

GET /api/reconciliation/batches?limit=50
→ 200 OK
Link: </api/reconciliation/batches?cursor=eyJvIjoiMjAyNi0wNy0wNVQxNDoyMjoxOVoifQ>; rel="next"

{
  "data":   [ { "id": "..." }, ... ],
  "next":   "eyJvIjoiMjAyNi0wNy0wNVQxNDoyMjoxOVoifQ",
  "limit":  50
}

5. Idempotency

For any POST that creates or mutates state (batches, exports, webhook subscriptions), send an Idempotency-Key header — a client-generated UUID v4. The API stores the first response for 24 hours and returns it verbatim on any retry with the same key, so a retried network request never creates a duplicate resource.

POST /api/reconciliation/batches
Idempotency-Key: 4a3d0c4b-2f21-4d0d-9b5a-9f6b0f2f2f7c
Authorization: Bearer $FVI_TOKEN

6. Rate limits

Every tenant is metered with a token bucket (default: 600 req/min sustained, burst 100 per second). Responses always carry the standard headers:

RateLimit-Limit:     600
RateLimit-Remaining: 587
RateLimit-Reset:     42        # seconds until refill
Retry-After:         2         # only sent on 429

On 429 Too Many Requests, back off using exponential jitter — the safe minimum is Retry-After.

7. Webhooks

Subscribe via POST /api/webhooks with a target URL and an event filter. Each delivery is signed with HMAC-SHA256 over the raw body using your per-endpoint secret; verify signatures with a timing-safe comparison before you trust the payload. Deliveries carry a monotonically increasing webhook-id andwebhook-timestamp; reject any timestamp older than 5 minutes to prevent replay attacks.

POST /your/endpoint  HTTP/1.1
webhook-id:         evt_01JB3QK6H3Q0M8W2S4X7Y9Z1AB
webhook-timestamp:  1782529636
webhook-signature:  v1,sha256=8c...

Event catalogue: batch.completed, batch.failed, exception.created, exception.resolved, export.ready, connector.sync.completed.

8. Versioning & deprecation

The API follows SemVer 2.0. The current major is v4. Breaking changes ship in a new major only. When we deprecate a field or route, responses gain the Deprecation and Sunset headers (RFC 8594) with at least 12 months notice before removal.

Deprecation: true
Sunset:      Wed, 01 Jul 2027 00:00:00 GMT
Link:        <https://app-fvi.falconveritas.com/developers/changelog>; rel="deprecation"

9. SDK examples

curl

curl -sS https://app-fvi.falconveritas.com/api/reconciliation/batches \
  -H "Authorization: Bearer $FVI_TOKEN"

TypeScript (fetch)

const res = await fetch(
  "https://app-fvi.falconveritas.com/api/reconciliation/batches",
  { headers: { Authorization: `Bearer ${process.env.FVI_TOKEN}` } },
);
if (!res.ok) throw new Error(await res.text());
const { data, next } = await res.json();

Python (httpx)

import os, httpx
r = httpx.get(
  "https://app-fvi.falconveritas.com/api/reconciliation/batches",
  headers={"Authorization": f"Bearer {os.environ['FVI_TOKEN']}"},
  timeout=30,
)
r.raise_for_status()
print(r.json())

Java (HttpClient)

HttpRequest req = HttpRequest.newBuilder()
  .uri(URI.create("https://app-fvi.falconveritas.com/api/reconciliation/batches"))
  .header("Authorization", "Bearer " + System.getenv("FVI_TOKEN"))
  .GET().build();
HttpResponse<String> res = HttpClient.newHttpClient()
  .send(req, HttpResponse.BodyHandlers.ofString());

10. ERP connectors

Native connectors for SAP, Oracle EBS/Fusion, Finacle, Flexcube, and Tally normalize their ledgers into the FVI reconciliation schema. See docs/connectors/ in the platform documentation for setup runbooks, OAuth/credential flow, and the reconciliation output schema per connector.

11. Support

Email developers@falconveritas.com with the request_id from the failing response. Security issues: security@falconveritas.com — see also our disclosure policy at /.well-known/security.txt.