Docs
GitHubDiscord

Authentication

Authenticate Zoneless API requests with a secret API key.

Every API request must include a secret API key. Live keys start with sk_live_z_ and test keys start with sk_test_z_.

Choose an environment

Zoneless Cloud has separate live and test environments. Use a key with the matching API URL.

  • Live: https://api.zoneless.com with an sk_live_z_ key. Live mode uses Solana mainnet and real USDC.
  • Test: https://api-test.zoneless.com with an sk_test_z_ key. Test mode uses Solana devnet.
Environment variables
ZONELESS_API_KEY=sk_live_z_YOUR_API_KEY
ZONELESS_API_URL=https://api.zoneless.com

Get an API key

Zoneless Cloud

Your first live key is shown when you create your account. To create or revoke a key later, open Developers in the Platform Dashboard. Switch between live and test mode before managing keys.

Self-hosted Zoneless

The setup wizard creates your first platform API key. Your API URL is the address of your instance, such as http://localhost during local development or https://api.yourdomain.com in production.

Authenticate a request

Send your secret key in the x-api-key header with every direct API request.

The example reads the key from an environment variable, which keeps it out of shell history and source code.

Authenticated request
export ZONELESS_API_KEY="sk_live_z_YOUR_API_KEY"

curl https://api.zoneless.com/v1/balance \
  -H "x-api-key: $ZONELESS_API_KEY"

Use the Node.js SDK

Pass the API key and base URL when you create the client. The SDK adds the authentication header to each request.

Keep client initialization in server-side code. Do not import a client containing your secret key into an Angular or other browser bundle.

Initialize the client
import { Zoneless } from '@zoneless/node';

const apiKey = process.env.ZONELESS_API_KEY;
const apiUrl = process.env.ZONELESS_API_URL;

if (!apiKey || !apiUrl) {
  throw new Error('Missing Zoneless configuration');
}

const zoneless = new Zoneless(apiKey, apiUrl);

const balance = await zoneless.balance.retrieve();

Rotate or revoke a key

Create a replacement key before revoking the old one. Update the secret in your application, deploy the change, confirm that requests succeed, then revoke the old key.

If a key is exposed, revoke it immediately and replace it anywhere it was used. Check logs and recent activity for requests you do not recognize.

Authentication errors

A request without a valid key returns an authentication error. Check that:

  • The x-api-key header is present.
  • The key has not been revoked or copied with extra spaces.
  • The key prefix matches the live or test API URL.
  • Your self-hosted instance URL points to the API, not the dashboard.

See Errors for response formats and other API error types.

Next steps