API Authentication

Operations

API Authentication

This guide covers how backend systems authenticate Card API requests to FINCI.

Access is not public. Sandbox and production environments are provisioned only for approved FINCI integrations.

Use Webhook Handling for webhook endpoint controls and Security And Operations for credential, key-management, and operational security requirements.

Environment access model

Each environment is controlled through:

request signing with an issued API token and secret
environment-specific IP whitelisting

Credentials and network access must be treated as environment-specific production controls, not as application-level convenience settings.

API request authentication

Card API requests must originate from backend systems operated by the integrator.

For API access:

FINCI issues the authentication material for the relevant environment
requests must be sent over TLS
source IPs must be whitelisted for the relevant environment
production credentials must be isolated from sandbox and other non-production use

FINCI issues two environment-specific authentication values:

an issued API token, sent in X-Auth-Token
an issued API secret, used only to calculate X-Auth-Signature

Every authenticated request also includes:

X-Auth-Timestamp, sent as a Unix timestamp in UTC seconds
X-Auth-Signature, calculated as an HMAC-SHA256 hex digest

For requests with a JSON body, the signature input is:

<timestamp><request_path><canonical_json_body>

For requests without a body, use an empty string for the body portion.

Sign the exact request path that is sent on the wire. In the provided Python example, requests are signed with the /api/v1/... path, so that same /api/v1/... value must be used in both the request URL and the signature input.

Python signing example

The following example is adapted from an internal test script and sanitized for documentation use:

import canonicaljson
import hashlib
import hmac
import time

API_TOKEN = "<issued-by-finci>"
API_SECRET = "<issued-by-finci>"


def build_headers(api_token: str, api_secret: str, request_path: str, body: dict | None) -> dict[str, str]:
    timestamp = str(int(time.time()))
    canonical_body = ""

    if body is not None:
        canonical_body = canonicaljson.encode_canonical_json(body).decode("utf-8")

    signature = hmac.new(
        api_secret.encode("utf-8"),
        f"{timestamp}{request_path}{canonical_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return {
        "X-Auth-Token": api_token,
        "X-Auth-Signature": signature,
        "X-Auth-Timestamp": timestamp,
    }

Example signed requests

Example PATCH request with a JSON body:

import requests

API_URL = "https://<sandbox-or-production-host>"
token_id = "<20-digit-card-token-id>"

request_path = f"/api/v1/update-card-status/{token_id}"
payload = {
    "token_status": "active",
}

headers = build_headers(API_TOKEN, API_SECRET, request_path, payload)

response = requests.patch(
    f"{API_URL}{request_path}",
    json=payload,
    headers=headers,
    timeout=10,
)

Example GET request without a body:

import requests

API_URL = "https://<sandbox-or-production-host>"
token_id = "<20-digit-card-token-id>"

request_path = f"/api/v1/get-card/{token_id}"
headers = build_headers(API_TOKEN, API_SECRET, request_path, None)

response = requests.get(
    f"{API_URL}{request_path}",
    headers=headers,
    timeout=10,
)

Webhook Handling Security And Operations

Built with