Skip to content

authentication.mdx

Latest commit

 

History

History
151 lines (105 loc) · 4.08 KB

authentication.mdx

File metadata and controls

151 lines (105 loc) · 4.08 KB
title Authentication
description How to authenticate with the ZendFi API using Bearer tokens and API keys.

Authentication

Every request to the ZendFi API must include a valid API key. Keys are scoped to a specific mode (test or live) and tied to your merchant account.

API Key Format

ZendFi API keys follow a predictable format that encodes their mode:

Prefix Mode Network Purpose
zfi_test_ Test Solana Devnet Development and testing
zfi_live_ Live Solana Mainnet Production transactions

The SDK and API automatically route requests to the correct Solana network based on the key prefix. You do not need to specify devnet or mainnet anywhere -- it is determined by the key.

Using Your API Key

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer zfi_test_abc123def456

With the SDK

The SDK reads your key from the ZENDFI_API_KEY environment variable automatically:

// Zero-config: reads from process.env.ZENDFI_API_KEY
import { zendfi } from '@zendfi/sdk';

const payment = await zendfi.createPayment({ amount: 50 });

You can also pass it explicitly:

import { ZendFiClient } from '@zendfi/sdk';

const client = new ZendFiClient({
  apiKey: 'zfi_test_your_key_here',
});

With cURL

curl -X POST https://api.zendfi.tech/api/v1/payments \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "currency": "USD"}'

Environment Variables

The SDK checks these environment variables in order:

Variable Framework
ZENDFI_API_KEY Any (Node.js)
NEXT_PUBLIC_ZENDFI_API_KEY Next.js
REACT_APP_ZENDFI_API_KEY Create React App
Never expose your API key in client-side code. The `NEXT_PUBLIC_` and `REACT_APP_` prefixes are supported for convenience, but API calls should always be made from your server. Client-side exposure of your key allows anyone to create payments on your behalf.

Managing API Keys

Via the Dashboard

Your primary API keys are available in the ZendFi Dashboard under Settings.

Via the API

You can also manage keys programmatically:

# List all keys
curl https://api.zendfi.tech/api/v1/keys \
  -H "Authorization: Bearer zfi_test_your_key"

# Create a new key
curl -X POST https://api.zendfi.tech/api/v1/keys \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Backend", "mode": "live"}'

# Rotate a key
curl -X POST https://api.zendfi.tech/api/v1/keys/{key_id}/rotate \
  -H "Authorization: Bearer zfi_test_your_key"

Via the CLI

zendfi keys list
zendfi keys create --name "CI/CD Pipeline" --mode test
zendfi keys rotate key_abc123

Key Rotation

When you rotate a key, the old key is immediately invalidated and a new one is returned. Make sure to update your environment variables promptly.

Consider using separate keys for different environments (staging, production) and services. This limits the blast radius if a key is compromised and makes audit logs more useful.

Error Responses

If authentication fails, the API returns a 401 status code:

{
  "error": "Invalid or expired API key",
  "code": "authentication_failed"
}

Common causes:

  • Missing Authorization header
  • Incorrect key prefix (typo or malformed key)
  • Revoked or rotated key
  • Using a test key against a live-only endpoint (or vice versa)

Rate Limits

Authenticated requests are rate-limited per merchant:

Endpoint Category Limit Window
Payment operations 50 requests 1 hour
Dashboard operations 200 requests 1 hour
All other endpoints 100 requests 1 hour

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1709312400

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.