Authentication
All merchant endpoints authenticate with an API key sent in the X-Api-Key header:
curl https://api-staging.finomesh.com/api/v1/payments \
-H "X-Api-Key: $FINOMESH_API_KEY"
Getting your API key
- Sign in to the merchant dashboard (
https://dashboard.finomesh.com). - Create a gateway (or open an existing one). A gateway represents one integration — it owns its payments, its allowed crypto assets, its fee settings, and its webhook signing secret.
- Copy the gateway's API key.
Your gateway must be in verified status before its API key is accepted; an unverified gateway's key is rejected with 401 auth_api_key_invalid.
The API key identifies your gateway and can create payments and read their outcomes. Never embed it in a browser bundle, a mobile app, or client-side code — all API calls must originate from your server.
Scope
The API key is scoped to its gateway. You can only see and verify payments that belong to the gateway the key was issued for — a payment ID from another gateway returns 404 not_found (not 403), so payment IDs cannot be probed across accounts.
Failure modes
| HTTP status | Error code | Meaning | How to fix |
|---|---|---|---|
| 401 | auth_api_key_invalid | Header missing, key unknown, or the gateway is not verified. | Send the X-Api-Key header with a valid key from a verified gateway. |
| 403 | forbidden | The key is valid but lacks the permission for this endpoint. | Use a key whose gateway has the required permission for this endpoint. |
The error envelope is described in the API overview.
Other credentials
| Credential | Used for | Where to get it |
|---|---|---|
API key (X-Api-Key) | All merchant API calls | Dashboard → your gateway |
| Webhook signing secret | Verifying the X-Webhook-Signature header on incoming webhooks | Dashboard → your gateway → webhook secret |
The webhook secret is a separate value from the API key — generating or rotating one never affects the other.