Agent Provider

You are an agent provider if your organization users acquire resources from merchants and services. In most organizations, each organization user represents one of your customers (end users). This page describes each setup step and the API call behind it. For what an organization is and how onboarding works, see the Organization Guide.

Before you start: This page is written for your organization's administrators. It assumes Skyfire has onboarded your organization and that you have your organization ID and an administrator user API key. Skyfire issues the first one to your designated administrator. All endpoints below are relative to your environment's base URL (see Environments). Every call authenticates with the skyfire-api-key header (see API Authentication).

0. How organization users map to your customers

The structure of your organization users generally follows the structure of your existing customer base. An organization user typically represents one of the following:

• A customer individual. One organization user per person, with their own identity. For example, a retail bank gives each account holder an organization user whose agents pay bills and subscriptions at other companies (B2C). The bank (or Skyfire) runs KYC (Know Your Customer) on each account holder, which confirms that the account holder is a real, identifiable person.
• A customer organization. One organization user per customer organization, with a shared identity. For example, a commercial bank gives each business client one organization user, shared across the business, whose agents pay supplier invoices (B2B). The bank (or Skyfire) runs KYB (Know Your Business) on each client, which confirms that the client is a legitimate, registered business.

1. Create organization users

Organization users are created with an administrator user API key. Each organization user has one of two roles:

Your designated administrator can create additional administrators, so that more than one person on your team can manage organization users. Each new administrator receives their own administrator user API key. Any administrator can create organization users.

Skyfire automatically provisions for each new organization user:

• A buyer agent, which creates tokens on the organization user's behalf.
• An agent API key, which authenticates every call the buyer agent makes, such as creating tokens.

{
  "email": "[email protected]",
  "role": "MEMBER"
}

{
  "userId": "f694008b-c3ca-4122-9f27-e1b18c19f677",
  "buyerAgent": {
    "id": "29d0562b-4e78-4428-85f3-38da8fad6be5",
    "apiKey": "82b033a0-00cc-4884-9269-004db880c2bf"
  }
}

To list organization users see Get Organization Users​.

2. Verify and set organization user PII

This step applies only if you intend for your organization's agents to create identity tokens (kya or kya-pay). If they will create only pay tokens, skip it. A pay token carries no identity claims.

An identity token tells a seller who is behind a buyer agent and whether that identity has been confirmed. The personally identifiable information (PII) you verify and set for each organization user determines what its buyer agent can do:

• More sellers accept their tokens. Many sellers require specific identity fields, or verified identity, before they provide a resource to a buyer agent. A buyer agent can share only the fields its organization user has on record. It can't transact with sellers that require verification its organization user lacks.
• Sellers can weigh the identity in each token. Each identity token names who verified its identity, in the verifier claim, so a seller can decide how far to trust it.
• Transactions qualify for Skyfire's protections. Verified identity supports secure transactions, access control, and selective disclosure, and it's required for Skyfire's Verified Service Guarantee.

Verify identity

Verification confirms that each organization user is who they claim to be. Customer individuals complete KYC (Know Your Customer). Customer organizations complete KYB (Know Your Business). Verify each organization user before you set their PII.

You choose who runs verification:

• Skyfire. Skyfire runs verification and is named as the verifier in the resulting token claims.
• Your organization (optional). You build and run your own verification process, which must meet Skyfire's criteria. Your organization is named as the verifier instead.

Reach out to your Skyfire contact to set up verification.

Once verification completes, every agent the organization user holds inherits its verification status. For how verification works across Skyfire, see Know Your Agent (KYA).

Set PII

Once an organization user is verified, set the PII that verification confirmed. Skyfire stores it securely. When a buyer agent creates an identity token, Skyfire discloses its organization user's PII in the token's hid claim. Each token includes the user's email, plus the fielsds the seller lists in its humanIdentityRequirement. If a seller requires a field you haven't set, the buyer agent can't meet that seller's requirements.

Set your designated administrator's PII first, because Skyfire uses it to fill the apd claim in every identity token your organization users create.

  {
    "data": {
      "person": { "firstName": "Ada", "lastName": "Lovelace", "birthdate": "1990-12-10" },
      "phoneNumbers": [
        { "type": "Mobile", "countryCode": "1", "areaCode": "415", "number": "5550142" }
      ],
      "addresses": [
        { "type": "Home", "street1": "1 Analytical Way", "city": "San Francisco", "state": "CA", "zip": "94105", "countryCode": "US" }
      ]
    }
  }

See the full PII attribute catalog at Identity Fields.

3. Facilitate token creation

A buyer agent creates tokens with its organization user's buyer agent API key. You choose who makes the calls:

• Your organization users. Direct them to call Skyfire's APIs themselves, and give them their buyer agent API keys.
• Your organization. Create tokens on their behalf, using each organization user's buyer agent API key. For example, your organization users call your own service, which calls Skyfire for them. You build and run that service, and you hold the buyer agent API keys.

The calls are the same either way. Every token carries your organization in the apd claim. See Your organization in every token.

Which transactions do you want your organization users' buyer agents to make? Each option below uses its own token types and setup. Organizations that enable payments typically choose either coin or payment cards.

{
  "type": "kya",
  "sellerServiceId": "22530a0c-3949-409d-9bad-56ea69703b0e"
}

    { "token": "eyJhbGciOi..." }

Track tokens

const BASE = process.env.SKYFIRE_API_BASE_URL!;

async function skyfire<T>(path: string, apiKey: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      "content-type": "application/json",
      "skyfire-api-key": apiKey,
      ...init?.headers,
    },
  });
  if (!res.ok) throw new Error(`${path} -> ${res.status}: ${await res.text()}`);
  return res.json() as Promise<T>;
}

// Organization management, with an administrator user API key
const ADMINISTRATOR_KEY = process.env.SKYFIRE_ADMINISTRATOR_API_KEY!;

export async function createUser(email: string, role: "ADMIN" | "MEMBER" = "MEMBER") {
  return skyfire<{
    userId: string;
    buyerAgent: { id: string; apiKey: string };
    userApiKey?: string;
  }>("/api/v1/organizations/users", ADMINISTRATOR_KEY, {
    method: "POST",
    body: JSON.stringify({ email, role }),
  });
}

export async function setPersonalData(userId: string, data: object) {
  return skyfire(`/api/v1/organizations/users/$USERID/personal-data`, ADMINISTRATOR_KEY, {
    method: "POST",
    body: JSON.stringify({ data }),
  });
}

// Agent operations, with that user's buyer agent API key
export async function createToken(
  agentKey: string,
  body: {
    type: "kya" | "pay" | "kya-pay";
    tokenAmount?: string;
    sellerServiceId: string;
    buyerTag?: string;
    expiresAt?: number;
  },
) {
  const { token } = await skyfire<{ token: string }>("/api/v1/tokens", agentKey, {
    method: "POST",
    body: JSON.stringify(body),
  });
  return token;
}

// Once per customer
const user = await createUser("[email protected]");
await setPersonalData(user.userId, { person: { firstName: "Ada", lastName: "Lovelace" } });

// Each time their agent accesses a seller service
const token = await createToken(user.buyerAgent.apiKey, {
  type: "kya",
  sellerServiceId: "b7e2f1a0-...",
  buyerTag: "session-8841",
});

Next steps

• To pay seller services with payment cards, see Agentic Commerce with Payment Cards.
• To run a single seller that your organization users buy from, see Sell to Your Customers' Agents.