Authentication & Headers

Every FinCard Virtual API request must carry a valid Bearer JWT token and a set of required context headers. Missing any of them returns HTTP 400 Missing required header(s).

Step 1 — Obtain a Session Token

Call the login endpoint once to obtain a short-lived JWT. Pass it as Authorization: Bearer <token> in all subsequent requests.

POST /api/auth/login
Content-Type: application/json
X-Tenant-ID: <your-tenant-id>
X-Forwarded-For: <client-ip>
X-Forwarded-From: <your-app-name>
platform: web
deviceId: <device-or-session-id>

Request body:

{
  "email": "user@your-domain.com",
  "password": "your-password",
  "tenantId": "your-tenant-id"
}

Response:

{
  "accessToken": "eyJ0eXAiOiJKV1Qi...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

expiresIn is in seconds. Tokens are valid for 1 hour. Re-authenticate before expiry — there is no refresh token endpoint.

Step 2 — Include Headers on Every Request

All 46 FinCard Virtual endpoints require the following headers:

Header	Required	Example	Description
`Authorization`	Yes	`Bearer eyJ0eXAi...`	JWT from login
`Content-Type`	Yes	`application/json`	Always JSON
`X-Tenant-ID`	Yes	`tenant_acme`	Your tenant identifier
`X-Forwarded-For`	Yes	`203.0.113.42`	End-user IP address
`X-Forwarded-From`	Yes	`my-backend-service`	Originating service name
`platform`	Yes	`web` \| `ios` \| `android`	Client platform
`deviceId`	Yes	`device-abc-123`	Unique device or session ID
`User-Agent`	No	`MyApp/2.1`	Client user-agent (recommended)

X-Forwarded-For, X-Forwarded-From, platform, and deviceId are validated server-side. A 400 Missing required header(s) error is returned if any are absent.

Complete Request Example

curl -X POST https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme" \
  -H "X-Forwarded-For: 203.0.113.42" \
  -H "X-Forwarded-From: my-backend" \
  -H "platform: web" \
  -H "deviceId: device-abc-123" \
  -d '{ "cardNo": "FC-XXXX-XXXX" }'

Response Envelope

Every response — success or error — is wrapped in the same envelope:

{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": { ... }
}

Field	Type	Description
`success`	Boolean	`true` = operation succeeded
`code`	Integer	`200` = OK, `-1` = business error, `401` = unauthorized, `500` = server error
`msg`	String	Human-readable status message
`data`	Object \| Array	Response payload (varies per endpoint)

Even HTTP 200 responses can have "success": false for business-level errors (e.g. card not found, insufficient balance). Always check success and code.

Error Reference

HTTP	`code`	Cause	Action
400	500	Missing required header	Add all required headers
401	401	Missing or expired token	Re-authenticate via `/api/auth/login`
401	401	Empty authorization token	Include `Authorization: Bearer <token>`
200	-1	Business error (e.g. card not found)	Check `msg` for details
200	200	Success	Process `data` payload

SDK / Script Example (PowerShell)

# 1. Login
$loginBody = @{
    email    = "user@domain.com"
    password = "your-password"
    tenantId = "your-tenant-id"
} | ConvertTo-Json -Compress

$loginResp = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/auth/login" `
    -Method Post `
    -Headers @{
        "Content-Type"     = "application/json"
        "X-Tenant-ID"      = "your-tenant-id"
        "X-Forwarded-For"  = "127.0.0.1"
        "X-Forwarded-From" = "my-script"
        "platform"         = "web"
        "deviceId"         = "script-device-001"
    } `
    -Body $loginBody

# 2. Use token in all subsequent calls
$headers = @{
    "Authorization"    = "Bearer $($loginResp.accessToken)"
    "Content-Type"     = "application/json"
    "X-Tenant-ID"      = "your-tenant-id"
    "X-Forwarded-For"  = "127.0.0.1"
    "X-Forwarded-From" = "my-script"
    "platform"         = "web"
    "deviceId"         = "script-device-001"
}

# 3. Call any endpoint
$cardInfo = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info" `
    -Method Post -Headers $headers -Body '{"cardNo":"FC-XXXX-XXXX"}'

Connectors

PaaS Journey

PaaS Operations

FinCard Virtual

Authentication & Headers

Authentication & Headers

Step 1 — Obtain a Session Token

Step 2 — Include Headers on Every Request

Complete Request Example

Response Envelope

Error Reference

SDK / Script Example (PowerShell)

​Authentication & Headers

​Step 1 — Obtain a Session Token

​Step 2 — Include Headers on Every Request

​Complete Request Example

​Response Envelope

​Error Reference

​SDK / Script Example (PowerShell)

Authentication & Headers

Step 1 — Obtain a Session Token

Step 2 — Include Headers on Every Request

Complete Request Example

Response Envelope

Error Reference

SDK / Script Example (PowerShell)