Agent Accounts

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.

Reach for this flow when:

• an autonomous agent needs an inbox on first boot, with no human in the loop
• you want to defer real account ownership until a human confirms an email address
• you're prototyping and don't want to create a dashboard account up front

When 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.

Both operations live under client.agent (AgentResource), exported from @primitivedotdev/sdk/api.

Create an agent account#

Call 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.

1. 1

   Construct an unauthenticated client#

   Build a PrimitiveApiClient with no apiKey. The agent-account endpoint is one of the few operations that runs with no auth at all.

   import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
   
   const client = createPrimitiveClient({});
   

2. 2

   Call client.agent.createAccount#

   Pass 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.

   import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
   
   const client = createPrimitiveClient({});
   const account = await client.agent.createAccount({});
   

3. 3

   Store the API key and start sending#

   The 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:

   import primitive from "@primitivedotdev/sdk";
   
   const agentClient = primitive.client({ apiKey: agentApiKey });
   
   await agentClient.reply(email, "Thank you for your email.");
   

Upgrade to a developer account (email-claim flow)#

Run 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.

1. 1

   Start the claim#

   Call 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.

   import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
   
   const client = createPrimitiveClient({ apiKey: agentApiKey });
   
   const claim = await client.agent.claimStart({
     email: "owner@example.com",
   });
   

   This sends a verification code to owner@example.com and returns an AgentClaimStartResult carrying the claim session id and resend timing.

2. 2

   Confirm the verification code#

   Once 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.

   const upgraded = await client.agent.claimVerify({
     verification_code: "123456",
   });
   

3. 3

   Verify the upgrade#

   On 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 if you need to confirm the new plan programmatically.

Doing this from the CLI#

Run primitive 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.

Next steps#