Skip to main content

OAuth client setup

This recipe shows how to create an OAuth 2.0 client for third-party integrations. FVI supports the standard OAuth 2.0 authorization code flow with PKCE, suitable for integrations with vendor portals, automated jobs, and embedded analytics.

Endpoint​

POST /v1/oauth/clients

Creates a new OAuth 2.0 client in the tenant. The client is identified by a client_id and secured by a client_secret (returned only at creation time).

Prerequisites​

  • A valid tenantId and bearer JWT.
  • The user must have the tenant_admin role.
  • Idempotency key is required.

Request body​

curl -X POST https://api.falconveritas.com/v1/oauth/clients \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendor Portal Integration",
    "description": "OAuth client for vendor portal integration to pull reconciliation status",
    "redirect_uris": ["https://vendor.example.com/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "scopes": ["read:reconciliations", "read:exceptions"],
    "token_lifetime_seconds": 3600,
    "refresh_token_lifetime_seconds": 2592000,
    "pkce_required": true,
    "idempotency_key": "oauth-fvi-$RANDOM"
  }'

Response​

{
  "client_id": "fvi_oc_abc123def456",
  "client_secret": "cs_live_xyz789abc123def456ghi789jkl012mno345pqr678stu901",
  "name": "Vendor Portal Integration",
  "redirect_uris": ["https://vendor.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scopes": ["read:reconciliations", "read:exceptions"],
  "token_lifetime_seconds": 3600,
  "refresh_token_lifetime_seconds": 2592000,
  "pkce_required": true,
  "created_at": "2026-08-22T16:00:00Z",
  "secret_rotated_at": null,
  "warning": "Store the client_secret securely. It will not be shown again."
}

Authorization flow​

1. Authorization request​

The third-party redirects the user to the FVI authorization endpoint:

https://app.falconveritas.com/oauth/authorize?
  response_type=code&
  client_id=fvi_oc_abc123def456&
  redirect_uri=https://vendor.example.com/oauth/callback&
  scope=read:reconciliations+read:exceptions&
  state=xyz123&
  code_challenge=BASE64URL(SHA256(code_verifier))&
  code_challenge_method=S256

2. Token exchange​

After the user authorizes, FVI redirects to the redirect_uri with an authorization code. The client exchanges the code for an access token:

curl -X POST https://api.falconveritas.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "fvi_oc_abc123def456",
    "client_secret": "cs_live_xyz789...",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://vendor.example.com/oauth/callback",
    "code_verifier": "ORIGINAL_CODE_VERIFIER"
  }'

3. Refresh token​

curl -X POST https://api.falconveritas.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "fvi_oc_abc123def456",
    "client_secret": "cs_live_xyz789...",
    "refresh_token": "REFRESH_TOKEN"
  }'

Use cases​

  • Vendor portal integration — let vendors query their reconciliation status via OAuth.
  • Automated jobs — generate long-lived refresh tokens for backend services.
  • Embedded analytics — power FVI analytics dashboards inside third-party portals.

Code samples​

TypeScript​

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const client = await fvi.oauth.createClient({
  name: 'Vendor Portal Integration',
  redirectUris: ['https://vendor.example.com/oauth/callback'],
  grantTypes: ['authorization_code', 'refresh_token'],
  scopes: ['read:reconciliations', 'read:exceptions'],
  pkceRequired: true,
  idempotencyKey: `oauth-fvi-${Date.now()}`,
});

console.log('Client ID:', client.client_id);
console.log('Client Secret (store securely!):', client.client_secret);

Python​

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

oauth_client = client.oauth.create_client(
  name="Vendor Portal Integration",
  redirect_uris=["https://vendor.example.com/oauth/callback"],
  grant_types=["authorization_code", "refresh_token"],
  scopes=["read:reconciliations", "read:exceptions"],
  pkce_required=True,
  idempotency_key=f"oauth-fvi-{int(time.time())}",
)
print("Client ID:", oauth_client.client_id)
print("Client Secret (store securely!):", oauth_client.client_secret)

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/oauth.ts.