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) Organization Administrator — 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, a valid key of the wrong role or kind, or an inactive key, agent, or organization user. 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.

Organization Administrator user key

Belongs to an Organization Administrator. Use it to manage your organization: its users, their agents and API keys, and your agent groups.

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 for a personal account 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.
Agent keys for organization users are issued by an Organization Administrator through the API. The first key for an agent is returned once, in the response that creates the agent: Create Organization User for the user's buyer, Create Organization User Seller Agent for a seller, and Enroll User in Agent Group for an agent group instance. Further keys, and replacements for a lost one, come from Create Agent API Key.
Organization Administrator user keys are set up by your Organization's Designated Administrator via the Create Organization User endpoint, with role ADMIN. Designated Administrators are set up by Skyfire directly. If you're interested in managing an organization, contact [email protected].

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, the key is the usual cause. The response points to it:

Response	Likely cause	Fix
Unauthorized (`401`)	The key isn't recognized (e.g. a typo, invalid value, or the wrong environment), or it's valid but the wrong role or kind for the action (e.g. a Seller key creating a token, or a Buyer key charging one); the message explains the mismatch.	Confirm the key is valid, matches the environment, and is the key for the role the endpoint expects.
Forbidden (`403`)	The key, the agent it belongs to, or the organization user who owns that agent is inactive. `API Key or Agent is not active` means the key was deactivated, or the agent was deactivated or unenrolled from its agent group. `Inactive Organization User` means the administrator's own user is deactivated.	Reactivate the key, agent, or user, or use a key from an active one. An unenrolled agent group instance stays inactive; enroll the user again for a new instance.
Bad Request (`400`) on Create Token	The key is valid and active, but the agent is an instance of an agent group that is deactivated. The message is `Agent group is deactivated`.	Reactivate the group with Update Agent Group. Every instance resumes at once.

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.

Still works, or still fails, right after a change

API key lookups are cached for up to 60 seconds. A key that was just deactivated may keep working for up to a minute, and a key that was just reactivated may keep failing for as long. Wait and retry before investigating further.

Treat every key as a secret — anyone holding it can act as that agent or administrator. If one is exposed, rotate it: in the Skyfire Dashboard for a personal account, or with Create Agent API Key and Deactivate Agent API Key for an organization user's agent.