--- updatedAt: 2026-10-05T18:51:33.000Z agentTools: projectIndex: https://docs.skyfire.xyz/llms.txt --- # Create Agent API Key As an Organization Admin, create a new API key for an agent belonging to a user in your organization. Authenticate with an **Organization Admin User API key**, sent in the `skyfire-api-key` header. Keys belonging to Organization Admins are accepted; a `MEMBER` key, or any Agent API key, is rejected with `401`. The agent is resolved through the ownership chain **organization → user → agent**, all scoped to your own organization. A user or agent that does not exist, belongs to another organization, or is not owned by the given user returns `404`. The agent must be **active**. An inactive agent also returns `404`. > The raw key is returned **only in this response** and cannot be retrieved again. Store it securely on receipt. Afterwards the key is identified only by its `id` and `lastFour`. The new key is active immediately. An agent can hold multiple active keys at once. Use the optional `notes` field to label keys for rotation tracking. # 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/{userId}/agents/{agentId}/api-keys": { "post": { "description": "As an Organization Admin, create a new API key for an agent belonging to a user in your organization.", "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the user who owns the agent. e.g. `\"906fc259-ef0a-4736-bdcd-c1d5a78db483\"`" }, { "in": "path", "name": "agentId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the agent to create a key for. e.g. `\"5d084831-4a11-4970-bf62-bb6fc0b9f3a2\"`" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 1000, "description": "Free-form label for the key, e.g. a rotation batch or environment name. At most 1000 characters." } } }, "examples": { "With notes": { "summary": "With notes", "value": { "notes": "Q3 rotation" } } } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the API key. Use this ID to activate or deactivate the key." }, "apiKey": { "type": "string", "description": "The raw API key. Returned only in this response — it cannot be retrieved again." }, "lastFour": { "type": "string", "description": "Last four characters of the key, for identifying it in listings." }, "active": { "type": "boolean", "description": "Whether the key currently authenticates. Always `true` on creation." }, "notes": { "type": "string", "description": "The label provided at creation. Omitted when none was set." }, "createdAt": { "type": "string", "description": "When the key was created. e.g. `\"2026-08-28T17:04:11.000Z\"`." } }, "required": [ "id", "apiKey", "lastFour", "active", "createdAt" ] }, "examples": { "Ok": { "summary": "Ok", "value": { "id": "c41d8f2b-6a3e-4b9c-8d1f-0e2a4b6c8d10", "apiKey": "b7e9d2c4-8f13-4a6e-9c05-1d2b8e4a9f2c", "lastFour": "9f2c", "active": true, "notes": "Q3 rotation", "createdAt": "2026-08-28T17:04:11.000Z" } } } } } }, "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": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "User not in your organization": { "summary": "User not in your organization", "value": { "code": "NOT_FOUND", "message": "User not found" } }, "Agent not owned by the user, or inactive": { "summary": "Agent not owned by the user, or inactive", "value": { "code": "NOT_FOUND", "message": "Agent not found" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Unprocessable Entity": { "summary": "Unprocessable Entity", "value": { "code": "VALIDATION_ERROR", "message": "Validation Error", "details": { "agentId": { "message": "Must be a valid UUID" } } } } } } } } }, "operationId": "post_api-v1-organizations-users-userid-agents-agentid-api-keys", "x-readme": { "code-samples": [ { "code": "curl -i -X POST 'https://api.skyfire.xyz/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/5d084831-4a11-4970-bf62-bb6fc0b9f3a2/api-keys' \\\n -H 'skyfire-api-key: ec0bf984-34f9-4e1e-a06e-984f3dfb089e' \\\n -H 'Content-Type: application/json' \\\n -d '{\"notes\":\"Q3 rotation\"}'", "language": "shell", "name": "cURL" }, { "code": "const res = await fetch(\n 'https://api.skyfire.xyz/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/5d084831-4a11-4970-bf62-bb6fc0b9f3a2/api-keys',\n {\n method: 'POST',\n headers: {\n 'skyfire-api-key': 'ec0bf984-34f9-4e1e-a06e-984f3dfb089e',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ notes: 'Q3 rotation' })\n }\n);\nconst { apiKey } = await res.json(); // shown once — store it securely", "language": "node", "name": "" }, { "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.skyfire.xyz\")\nheaders = {\n 'skyfire-api-key': 'ec0bf984-34f9-4e1e-a06e-984f3dfb089e',\n 'Content-Type': 'application/json'\n}\npayload = json.dumps({\"notes\": \"Q3 rotation\"})\nconn.request(\"POST\", \"/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/5d084831-4a11-4970-bf62-bb6fc0b9f3a2/api-keys\", payload, headers)\nres = conn.getresponse()\nprint(res.read().decode(\"utf-8\"))", "language": "python", "name": "" } ], "samples-languages": [ "shell", "node", "python" ] }, "summary": "Create Agent API Key" } } }, "x-readme": { "headers": [ { "key": "skyfire-api-key", "value": "" } ], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```