Authenticate with an Organization Admin User API key, sent in the skyfire-api-key header. Keys belonging to callers whose organization role is ADMIN are accepted; a MEMBER key, or any Agent API key, is rejected with 401.

The new user is always created in your organization. It is derived from the API key, and there is no orgId field in the request body.

The role you assign

What this call creates

A single request creates:

1. The organization user.
2. A buyer agent with a wallet. Without agentGroupId it is the user's own agent, named Buyer 1. With agentGroupId it is the user's instance of that agent group, named after the group.
3. An API key for that buyer agent, returned as buyerAgent.apiKey.
4. If role is ADMIN, an Organization Admin User API key, returned as userApiKey.

If any step fails, the whole transaction is rolled back and no user is created.

buyerAgent.apiKey and userApiKey are returned only in this response

and cannot be retrieved again. Store them securely before discarding the
response.

For role: "MEMBER", userApiKey is omitted from the response body entirely. It is not returned as null.

Creating the user into an agent group

Pass agentGroupId to enroll the new user in one of your organization's agent groups as part of creation. The buyer agent is then the user's instance of the group: its display name is the group's name, and tokens it mints carry that name as aid.name. The user gets no Buyer 1 agent; one can be added later with Create Organization User Buyer Agent, and the user can be enrolled in further groups with Enroll User in Agent Group.

The group must belong to your organization (404 otherwise) and be active (400 if deactivated). Both checks run before anything is provisioned.

Duplicate emails

An email is unique within your organization. If an active or deactivated user with the same email already exists, the request is rejected with 409 before anything is provisioned. Recover the existing user with Get Organization User by Email, which returns their id and agents; the original API keys cannot be retrieved, but new ones can be created with Create Agent API Key.