API Authentication

Every Skyfire API request authenticates the same way: a single HTTP header, skyfire-api-key. What changes is which key you put in it. You hold different keys for different roles — Buyer, Seller, and (for organizations) Enterprise Admin — and using the wrong one is the most common cause of failed requests. This page explains which key to use, and when.

skyfire-api-key: <YOUR_SKYFIRE_API_KEY>

All key types share this one header. How it fails tells you what's wrong: a key that isn't recognized returns 401 NOT_AUTHORIZED, while a valid key used for the wrong role returns 400 BAD_REQUEST with a message explaining the mismatch. See Troubleshooting below.

Which key does what

Buyer agent key

Belongs to a Buyer agent. Use it for everything a buyer does: creating tokens and inspecting its own tokens, charges, and wallet.

Seller agent key

Belongs to a Seller agent. Use it for everything a seller does: managing seller services and charging tokens after delivery.

Enterprise Admin user key

Belongs to an Enterprise Admin user. Use it to manage the people in your organization: not for token or service operations.

The single most common mistake: creating a token needs the Buyer key, but charging a token needs the Seller key. They are two different keys for two different agents in the same transaction.

Pick the right key for the request

Authenticate with your Buyer agent's API key when the buyer is acting (e.g. creating a token, or reviewing its own tokens, charges, and wallet balance).

curl -X POST https://api.skyfire.xyz/api/v1/tokens \
  -H "Content-Type: application/json" \
  -H "skyfire-api-key: <BUYER_AGENT_API_KEY>" \
  -d '{
    "type": "kya-pay",
    "sellerServiceId": "223bc3eb-9bcb-4e9b-afd6-f26ee0bd3894",
    "tokenAmount": "0.01"
  }'

Where keys come from

Buyer and Seller agent keys are created at the agent-account level in the Skyfire Dashboard. Each agent has its own unique keys, and an agent can hold more than one.
Enterprise Admin user keys are set up by Skyfire directly. If you're interested in managing an organization, contact [email protected]. Once you're an Enterprise Admin, you can create additional users and admins via the Create Enterprise User endpoint.

Keys are environment-specific. A Sandbox key only works against Sandbox, and a Production key only against Production. See Environments for the matching base URLs.

Troubleshooting auth errors

If a request is rejected, it oftentimes is the key. The response type points to the cuase:

Response	Likely cause	Fix
Unauthorized (`401`)	The key isn't recognized (e.g. a typo, invalid value, or the wrong environment).	Confirm the key is valid and matches the environment.
Bad request (`400`)	The key is valid but the wrong role for the action (e.g. a Seller key creating a token, or a Buyer key charging one).	Use the key for the role the endpoint expects.

Works in one environment but not the other

Keys don't cross environments. Confirm you're sending a Sandbox key to the Sandbox base URL, or a Production key to the Production base URL. See Environments.

Treat every key as a secret — anyone holding it can act as that agent or admin. Rotate keys in the Dashboard if one is exposed.