# API Keys and Authentication

> Authenticate server-side merchant API requests with API keys.

Canonical: https://stafiel.org/documentation/developer-integration/api-keys-and-authentication
Version: v1.0.0

Use API keys for server-to-server merchant API calls. Keep keys on your backend
only. Do not place them in browser JavaScript, mobile apps, checkout pages, or
client-side widget configuration.

## Base URL

https://api.stafiel.com

## Request Headers

Every API key request must include the authentication and client-mode headers.
Requests with JSON bodies must also include Content-Type: application/json.

Header
Required
Default
Description

X-API-Key
Yes
None
Merchant API key created in the Merchant Dashboard. Keep this value server-side only.

X-App-Client
Yes
None
Request mode identifier. Use merchant-client for live API keys.

Content-Type
Required for requests with a body
None
Use application/json when sending a JSON request body, such as checkout session creation.

Live API keys must use X-App-Client: merchant-client. Test API keys must use
X-App-Client: merchant-client-testnet. If the key mode and header mode do not
match, Stafiel returns 401 AUTH_FAILED.

### Header Example

X-API-Key: mk_live_your_api_key
X-App-Client: merchant-client
Content-Type: application/json

## Merchant ID

Most order endpoints require merchantId. The value must match the merchant
bound to the API key. Requests for another merchant are rejected.

## Rate Limits

API key requests are rate limited. Limits may vary by endpoint, merchant,
request mode, plan, traffic pattern, and operational risk controls.

When a request is rate limited, the API returns 429 RATE_LIMIT_EXCEEDED.
If the response includes Retry-After or rate-limit reset headers, wait for the
indicated time before retrying.

Design your integration to retry with backoff, avoid tight polling loops, and
reuse idempotency keys when retrying checkout session creation.

## Key Management

Create, rotate, and revoke API keys from the Merchant Dashboard. Store API keys
in a secret manager or server environment variable. Rotate a key immediately if
it may have been exposed.