Authentication & Headers

How to authenticate and which headers are required for every FinCard Virtual API call

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": "[e-mail]",
  "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    = "[e-mail]"
    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"}'