URL: /paas/fincard-virtual/authentication

---
title: 'Authentication & Headers'
description: '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.

```bash
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:**

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

**Response:**

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

<Note>
  `expiresIn` is in seconds. Tokens are valid for **1 hour**. Re-authenticate before expiry — there is no refresh token endpoint.
</Note>

---

## 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) |

<Warning>
  `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.
</Warning>

---

## Complete Request Example

```bash
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:

```json
{
  "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) |

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

---

## 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)

```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"}'
```