🔑 Authentication Headers

📘

Operating as a Web3 Merchant with customers that have individual wallets?
See Authentication Headers for Web3 Merchants

🔑 How to Generate API Key

View Section ›

Go to the Merchant Dashboard → API Keys Tab → Copy your API Key.
In your requests, set the Authorization header to your API Key.

🚧

Keep your API Key Secret!

📥 API Headers

View Section ›

Header	Description	Example
`Authorization`	This is the merchant API key. This authenticates a user making a request to Coinflow API.	`coinflow_sandbox_123abcdefg_123abcdefg`
`x-coinflow-auth-blockchain`	Blockchain that you are using.	`solana`, `eth`, `polygon`, `base`, `arbitrum`, `near`
`x-coinflow-auth-session-key`	A session key generated from Get Session Key.	`eyLhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ0...`
`x-coinflow-auth-user-id`	Unique customer identifier used by the merchant. Can be any string (UUID, username, etc). Not associated with Coinflow.	`user_12345`, `971e1de0-54a4-451d-8230-7fa13e6d2dae`, `myUsername`
`x-coinflow-auth-wallet`	Wallet public key or address. Use only if the user has a blockchain wallet.	`6zdj6f58ZfNDxDy6bArCDjVhWJ7Mwtigqh2M7VZYv9Qt`, `0x3B0423D73A5E8faFf2CB81fbC1EFb1f0F3470E3T`
`x-device-id`	Used to relate the request to device/session data collected via the Chargeback Protection SDK. Required if using Chargeback Protection.	`f0000c00-b0fe-0ab0-000d-c0000f000f00`

🔁 Server-to-Server Request Headers

View Section ›

Non-Web3 merchants must include an Authorization header (API key) when making requests to Coinflow's APIs, such as:

Merchant
Authentication
Marketplace
Off-Chain Payments

✅ Steps

Generate an API Key in Merchant Dashboard → API Keys → Create
Make your request using the API Key in the Authorization header

💻 Example (cURL)

// Request for Getting Merchant Withdraws
curl --request GET \
  --url https://api-sandbox.coinflow.cash/api/merchant/withdraws \
  --header 'Authorization: coinflow_sandbox_YOUR_API_KEY' \
  --header 'accept: application/json'

Client-to-Server Request Headers

Non-Web3 merchants must include a session key in the Authorization header when making client requests.
This is required for endpoints like Checkout, Customers, Subscriptions, and Withdraw.

✅ Steps

Generate an API Key via Merchant Dashboard → API Keys → Create
Get a Session Key
You'll need to provide:
- x-coinflow-auth-user-id: your internal customer identifier
- Authorization: your Merchant API Key
Make a client request using the session key

🚧

Session Keys are valid for 24 hours and must be renewed after expiration.

Example Implementation

// Example Request for Getting Session Key
curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/auth/session-key \
     --header 'Authorization: coinflow_sandbox_YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-user-id: test123'

// Response for Getting Session Key
{
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidGVzdDEyMyIsIm1lcmNoYW50SWQiOiJ0ZXN0dGVzdCIsImlhdCI6MTcyOTc4OTU3NiwiZXhwIjoxNzI5ODc1OTc2fQ.HvCOrraNCZjnsYQ1Cm96QkXRm-2GqVW-y_VXLMJcjTU"

//Example Request to Get Customer endpoint with Session Key
curl --location 'https://api-sandbox.coinflow.cash/api/customer/v2' \
--header 'accept: application/json' \
--header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidGVzdDEyMyIsIm1lcmNoYW50SWQiOiJ0ZXN0dGVzdCIsImlhdCI6MTcyOTc4OTU3NiwiZXhwIjoxNzI5ODc1OTc2fQ.HvCOrraNCZjnsYQ1Cm96QkXRm-2GqVW-y_VXLMJcjTU'

//Response to Get Customer endpoint with Session Key
{
    "customer": {
        "_id": "6706a50d707143b86d40e4e5",
        "blockchain": "user",
        "email": "[email protected]",
        "isBlocked": "NotBlocked",
        "chargebackProtectionEnabled": true,
        "merchant": "66211727a26b3cb28faaf97f",
        "failedAttemptSetting": "Standard",
        "verificationSetting": "Enforced",
        "exempt3DS": false,
        "createdAt": "2024-10-09T15:45:17.661Z",
        "__v": 0,
        "customerId": "test123",
        "bankAccounts": [
            {
                "alias": "Plaid Checking 0000",
                "token": "9a80b72f-bc89-4ccf-a4ec-f847508fec10",
                "routingNumber": "011401533",
                "last4": "0000",
                "accountHash": "a66621183ad216e4543f9004426a263ad58385f9",
                "rtpEligible": true,
                "reference": "668d43c036d527ce756f7298"
            }
        ]
    }
}