{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/node-sdk-agent-accounts","markdown_url":"https://test.abhinandan.one/node-sdk-agent-accounts.md","article":{"id":"31156528-98f6-429f-bcd4-3ec09785d2ac","article_slug":"node-sdk-agent-accounts","parent_article_slug":null,"parent_article_title":null,"kind":"guide","published_at":"2026-08-11T18:54:49.899492+00:00","keywords":["client.agent.createAccount","claimStart","claimVerify","agent account","email-claim flow","AgentResource"],"meta_description":"Create an agent account without an API key using client.agent.createAccount, then upgrade it to a developer account with claimStart and claimVerify.","og_image_url":null,"source_file_paths":["sdk-node/src/api/index.ts"],"recording_id":null,"replayable":false,"task_name":"Agent Accounts","category":"Node.js SDK","summary":null,"description":"Create a zero-touch Primitive agent account with no API key, then upgrade it to a full developer account through the email-claim flow using client.agent.","content_kind":"repo_page","content_markdown":"Use an **agent account** when your code needs to send and receive mail before a human has created a Primitive account or issued an API key. An agent account is a zero-touch account created with no authentication at all: call `client.agent.createAccount` (the unauthenticated account-creation method on `AgentResource`), get back a one-time API key and a provisioned managed inbox, and start replying immediately on the reply-only `agent` plan.\n\nReach for this flow when:\n\n- an autonomous agent needs an inbox on first boot, with no human in the loop\n- you want to defer real account ownership until a human confirms an email address\n- you're prototyping and don't want to create a dashboard account up front\n\nWhen the agent later needs full sending privileges instead of reply-only, upgrade it to a developer account with the **email-claim flow**: `claimStart` sends a verification code to a human's email and returns the claim session id plus resend timing, then `claimVerify` confirms the code and upgrades the account to the `developer` plan. The org id, API key, and managed inbox all carry over; the send cap lifts.\n\nBoth operations live under `client.agent` (`AgentResource`), exported from `@primitivedotdev/sdk/api`.\n\n<Tip>\n\nBuilding in Python or Go? Both SDKs implement the same agent-account and email-claim pattern under their generated agent operations. This page documents the canonical model using the Node.js SDK's `client.agent`; the request/response shapes are identical across languages.\n\n</Tip>\n\n## Create an agent account\n\nCall `client.agent.createAccount` on a client constructed without an API key; the endpoint is unauthenticated and returns a one-time API key (prefixed `prim_`, shown once) plus a provisioned managed inbox.\n\n<Steps>\n\n<Step title=\"Construct an unauthenticated client\">\n\nBuild a `PrimitiveApiClient` with no `apiKey`. The agent-account endpoint is one of the few operations that runs with no auth at all.\n\n```typescript\nimport { createPrimitiveClient } from \"@primitivedotdev/sdk/api\";\n\nconst client = createPrimitiveClient({});\n```\n\n</Step>\n\n<Step title=\"Call client.agent.createAccount\">\n\nPass the account-creation input (see the generated `CreateAgentAccountInput` type for the full field list). The response is an `AgentAccountResult` carrying the one-time API key and the provisioned managed inbox; check `AgentAccountResult` for exact field names.\n\n```typescript\nimport { createPrimitiveClient } from \"@primitivedotdev/sdk/api\";\n\nconst client = createPrimitiveClient({});\nconst account = await client.agent.createAccount({});\n```\n\n</Step>\n\n<Step title=\"Store the API key and start sending\">\n\nThe API key is returned exactly once. Persist it (secrets manager, encrypted storage) before you lose the response. Use it to build a normal client for `send`/`reply`/`forward`:\n\n```typescript\nimport primitive from \"@primitivedotdev/sdk\";\n\nconst agentClient = primitive.client({ apiKey: agentApiKey });\n\nawait agentClient.reply(email, \"Thank you for your email.\");\n```\n\n</Step>\n\n</Steps>\n\n<Warning>\n\nThe `agent` plan is **reply-only**: it can send mail only to addresses that have already sent it authenticated mail. It also has tight send limits. Plan around this until you upgrade the account.\n\n</Warning>\n\n## Upgrade to a developer account (email-claim flow)\n\nRun `claimStart` then `claimVerify`, both authenticated with the agent's own API key, to confirm a human's email address and upgrade the account to the `developer` plan. The account keeps its org id, API key, and managed inbox; the send cap lifts.\n\n<Steps>\n\n<Step title=\"Start the claim\">\n\nCall `claimStart` **authenticated as the agent** (use the agent's own API key from account creation). Pass the email address to send the verification code to.\n\n```typescript\nimport { createPrimitiveClient } from \"@primitivedotdev/sdk/api\";\n\nconst client = createPrimitiveClient({ apiKey: agentApiKey });\n\nconst claim = await client.agent.claimStart({\n  email: \"owner@example.com\",\n});\n```\n\nThis sends a verification code to `owner@example.com` and returns an `AgentClaimStartResult` carrying the claim session id and resend timing.\n\n</Step>\n\n<Step title=\"Confirm the verification code\">\n\nOnce the human retrieves the code from their inbox, confirm it with `claimVerify`, still authenticated with the agent's own API key. The input shape is the generated `VerifyAgentClaimInput`; it carries the verification code from the email.\n\n```typescript\nconst upgraded = await client.agent.claimVerify({\n  verification_code: \"123456\",\n});\n```\n\n</Step>\n\n<Step title=\"Verify the upgrade\">\n\nOn success, the account is on the `developer` plan. The org id, API key, and managed inbox are unchanged, and the send cap lifts. Re-check account status with the [account resource](node-sdk-account-resource) if you need to confirm the new plan programmatically.\n\n</Step>\n\n</Steps>\n\n<Tip>\n\nIf the verification code expires or the human hasn't received it, call `claimStart` again to resend. Respect the resend timing returned by the previous `claimStart` call to avoid a rate limit.</br>\n\n</Tip>\n\n## Doing this from the CLI\n\nRun [`primitive agent-upgrade`](cli-agent-upgrade), which drives the same claim-start then claim-verify sequence from the terminal, prompting for the email and the code. Reach for it when you're operating an agent account outside application code.\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Agent Accounts and Account Management API\" href=\"node-sdk-account-resource\">\n\nRead account details, storage stats, and inbox status once your agent account is upgraded.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Forwarding Email\" href=\"node-sdk-sending-email\">\n\nUse client.send, client.reply, and client.forward once your agent account can send.\n\n</Card>\n\n<Card title=\"Agent Account Upgrade from the CLI\" href=\"cli-agent-upgrade\">\n\nRun the same claim-start/claim-verify flow from the terminal with primitive agent-upgrade.\n\n</Card>\n\n<Card title=\"Node.js SDK Agent Guide\" href=\"node-sdk-agent-guide\">\n\nSee every import path and method signature for @primitivedotdev/sdk in one reference.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/sdk-node/src/api/index.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Agent+Accounts&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fnode-sdk-agent-accounts","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}