--- updatedAt: 2026-10-16T19:29:31.000Z agentTools: projectIndex: https://docs.skyfire.xyz/llms.txt --- # Create Organization User As an Organization Admin, create a new user in your organization, with a buyer agent, wallet, and API key. Optionally enroll the user in an agent group, making the buyer agent their instance of it. A duplicate email is rejected with 409 before anything is provisioned. 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 | `role` | Result | | -------- | ---------------------------------------------------------------------------------------- | | `MEMBER` | Standard organization user. | | `ADMIN` | Organization Admin. Additionally receives a user API key, returned once as `userApiKey`. | ### 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](create-organization-user-buyer-agent.md), and the user can be enrolled in further groups with [Enroll User in Agent Group](enroll-agent-group-user.md). 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](get-organization-user-by-email.md), which returns their `id` and agents; the original API keys cannot be retrieved, but new ones can be created with [Create Agent API Key](create-agent-api-key.md). # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "skyfire-agent-and-token-apis", "version": "1.0" }, "servers": [ { "url": "https://api.skyfire.xyz" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "skyfire-api-key", "in": "header" } } }, "security": [ { "sec0": [] } ], "paths": { "/api/v1/organizations/users": { "post": { "summary": "Create Organization User", "description": "As an Organization Admin, create a new user in your organization, with a buyer agent, wallet, and API key. Optionally enroll the user in an agent group, making the buyer agent their instance of it. A duplicate email is rejected with 409 before anything is provisioned.", "operationId": "create-enterprise-user", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "Email address of the new organization user. Must be unique within your organization. e.g. `chloe@gmail.com`" }, "role": { "type": "string", "description": "Organization role for the new user. `MEMBER` creates a standard organization user. `ADMIN` creates an Organization Admin, which additionally returns `userApiKey` in the response.", "enum": [ "MEMBER", "ADMIN" ] }, "agentGroupId": { "type": "string", "format": "uuid", "description": "Enroll the new user in this agent group. The buyer agent is then the user's instance of the group, named after it, instead of an ungrouped `Buyer 1`. The group must belong to your organization and be active." } } }, "examples": { "Standard user": { "summary": "Standard user", "value": { "email": "chloe@gmail.com", "role": "MEMBER" } }, "User enrolled in an agent group": { "summary": "User enrolled in an agent group", "value": { "email": "chloe@gmail.com", "role": "MEMBER", "agentGroupId": "215f6804-cd50-4c42-9c14-98db7312718d" } } } } }, "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "examples": { "Role: ADMIN": { "summary": "Role: ADMIN", "value": { "userId": "4da70647-e1f0-4508-bef0-8866bb7a3d01", "buyerAgent": { "id": "c01fe0c7-517e-446e-88d5-b10d84974b87", "apiKey": "e4661d3e-43a9-4d38-927c-ea7d2ff92403" }, "userApiKey": "60b664e7-8fc1-48bf-8362-83555e80b2bd" } }, "Role: MEMBER": { "summary": "Role: MEMBER", "value": { "userId": "906fc259-ef0a-4736-bdcd-c1d5a78db483", "buyerAgent": { "id": "5d084831-4a11-4970-bf62-bb6fc0b9f3a2", "apiKey": "aff074ee-ea8b-4643-bad1-913a534a5d7a" } } } }, "schema": { "type": "object", "properties": { "userId": { "type": "string", "example": "906fc259-ef0a-4736-bdcd-c1d5a78db483", "description": "Unique identifier of the newly created organization user." }, "buyerAgent": { "type": "object", "properties": { "id": { "type": "string", "example": "5d084831-4a11-4970-bf62-bb6fc0b9f3a2", "description": "Unique identifier of the buyer agent. With `agentGroupId`, this is the user's instance of the group." }, "apiKey": { "type": "string", "example": "aff074ee-ea8b-4643-bad1-913a534a5d7a", "description": "API key for the buyer agent. Returned only in this response and cannot be retrieved again, store it securely." } }, "description": "The user's buyer agent." }, "userApiKey": { "type": "string", "description": "Organization Admin API key for the new user. Present only when `role` is `ADMIN`; for `MEMBER` the field is omitted from the body rather than returned as null. Returned only in this response and cannot be retrieved again, store it securely." } }, "required": [ "userId", "buyerAgent" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "examples": { "Agent group deactivated": { "summary": "Agent group deactivated", "value": { "code": "BAD_REQUEST", "message": "Agent group is deactivated; reactivate it before enrolling users" } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "BAD_REQUEST" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "code": "NOT_AUTHORIZED", "message": "Invalid Organization User API Key" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "examples": { "Agent group not in your organization": { "summary": "Agent group not in your organization", "value": { "code": "NOT_FOUND", "message": "Agent group not found" } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "examples": { "Email already in your organization": { "summary": "Email already in your organization", "value": { "code": "CONFLICT", "message": "An organization user with email ada@example.com already exists" } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "CONFLICT" }, "message": { "type": "string", "example": "An organization user with email ada@example.com already exists" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "examples": { "Unprocessable Entity": { "summary": "Unprocessable Entity", "value": { "code": "VALIDATION_ERROR", "message": "Validation Error", "details": { "request.email": { "message": "Must be a valid email address" } } } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Validation Error" }, "details": { "type": "object", "properties": { "request.email": { "type": "object", "properties": { "message": { "type": "string", "example": "Must be a valid email address" } } } } } } } } } } }, "x-readme": { "code-samples": [ { "code": "curl -i -X POST 'https://api.skyfire.xyz/api/v1/organizations/users' \\\n -H 'skyfire-api-key: 039695d8-bb96-408d-b31a-6afddf0c33cb' \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\":\"chloe@gmail.com\",\"role\":\"MEMBER\",\"agentGroupId\":\"215f6804-cd50-4c42-9c14-98db7312718d\"}'", "language": "shell", "name": "cURL" }, { "code": "const res = await fetch(\n 'https://api.skyfire.xyz/api/v1/organizations/users',\n {\n method: 'POST',\n headers: {\n 'skyfire-api-key': '039695d8-bb96-408d-b31a-6afddf0c33cb',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ email: 'chloe@gmail.com', role: 'MEMBER' })\n }\n);\nconsole.log(await res.json());", "language": "node", "name": "" }, { "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.skyfire.xyz\")\nheaders = {\n 'skyfire-api-key': '039695d8-bb96-408d-b31a-6afddf0c33cb',\n 'Content-Type': 'application/json'\n}\npayload = json.dumps({\"email\": \"chloe@gmail.com\", \"role\": \"MEMBER\"})\nconn.request(\"POST\", \"/api/v1/organizations/users\", payload, headers)\nres = conn.getresponse()\nprint(res.read().decode(\"utf-8\"))", "language": "python", "name": "" } ], "samples-languages": [ "shell", "node", "python" ] } } } }, "x-readme": { "headers": [ { "key": "skyfire-api-key", "value": "" } ], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```