Organization Guide

As an organization, you operate an agent platform: you manage a group of users, and the agents that act for them, centrally, under one umbrella. Most commonly, each organization user represents one of your customers (end users). This gives every customer its own presence on Skyfire, with its own identity, wallet, and agents acting on its behalf.

Onboarding as an organization requires an agreement. Reach out to [email protected] to get started.

Your organization's shape

Your organization takes one of three shapes, depending on whether your customers buy, sell, or both. Each card links to the full guide for that shape. If you are a marketplace organization, follow both guides.

Agent provider

Your organization users acquire resources from merchants. For example, Sequentum's customers offer their identity in exchange for web data.

Resource provider/seller

Your organization users offer resources, such as APIs, MCP servers, or webpages. For example, Blackhawk Network's customers sell gift cards to agents.

Marketplace

Your organization users do both. For example, Buildship's customers buy and sell workflow automations to/from agents.

In a marketplace organization, the same organization user can hold both a buyer agent and a seller agent.

What onboarding unlocks

Each of your customers get their own presence on Skyfire. Every organization user has its own identity and wallet, and its own agents to create or receive tokens.
You define agent identities once and roll them out to every customer. An agent group is one named agent, such as ShoppingBot, that each enrolled customer gets their own instance of, with its own wallet and keys. Rename or pause the group and every instance follows.
Your organization is named in every token. Every token your organization users create identifies your organization, so a merchant or service can see which organization the agent is acting for.
You decide who verifies your customers. Skyfire can verify them for you, or you can run your own verification process and be named as the verifier instead.
You manage everything centrally. You create and manage all of your organization users from one account, and you stay your customers' only point of contact. Skyfire doesn't engage with your customers directly.

Getting onboarded

Share your setup with your Skyfire contact. They create your organization and assign it an organization ID. You also choose your organization's designated administrator (organization's point of contact), and Skyfire issues that administrator a user API key.

From there, follow the guide for your organization's shape: Agent Provider, Resource Provider, or both.

How an organization is structured

See Platform Structure for how these fit into Skyfire as a whole.

Piece	What it is
Organization	Your agent platform on Skyfire, identified by its organization ID. Every organization user (and their agents) that you create belongs to it.
Organization user	End user within your organization, identified by email. Most commonly, one of your customers.
Designated administrator	Your organization's point of contact. Each organization has exactly one. Has administrator privileges.
Buyer agent	Acts on an organization user's behalf to acquire resources from merchants. It discovers, creates tokens, and purchases resources from seller agents. A user holds one buyer agent of their own, plus one instance of each agent group they are enrolled in.
Seller agent	Acts on an organization user's behalf to offer resources to buyers. It receives, verifies, and charges tokens.
Agent group	An agent identity your organization defines once and enrolls users in. Owned by the organization, not by a user.
Instance	A user's own buyer agent for an agent group: named after the group, with its own wallet and API keys. Created when the user is enrolled.

Ensure you are using the right API key for the right actor. Administrators and agents are each issued their own API key. See API Authentication for more details.

Your organization in every token

Every token your organization users create has an apd claim, representing agent platform identity, i.e. your organization.

What apd looks like in practice

Here's a partial decoded token showing apd in context:

{
  ...
  "apd": {
    "id": "1ae68a2d-1266-4647-98be-f9f72eed4076",
    "name": "ACME Shopping",
    "email": "[email protected]",
    ...
  },
  ...
}

From this partial decoded token, a merchant or service can see that the buyer agent was acting on behalf of ACME Shopping. If it needs to reach a real person for details, [email protected] is the contact. This gives every token an accountability trail: an agent's actions are traceable to a real, identifiable party.

Skyfire populates apd.email from your designated administrator. See Agent platform identity (apd) sub-claims for the full list of fields it contains.

The token's aid claim identifies the agent itself: aid.id is the agent's own ID, and aid.name is its display name, which for an agent group instance is the group's name. A merchant can therefore tell both which organization and which individual agent acted. See Agent Identity (aid) sub-claims.

Set your designated administrator's personal data before creating any tokens. Because that identity travels in every token your organization users create, a designated administrator without personal data leaves apd incomplete for every agent underneath it.

Next steps

To set up your organization as an agent provider, see Agent Provider.
To set up your organization as a resource provider, see Resource Provider.
To set up your organization as a marketplace, follow both guides above.
To run a single resource provider for your agent provider organization, see Sell to Your Customers' Agents.
To roll one agent identity out to all of your customers, see Agent groups in the Agent Provider guide.