---
title: "Agent Accounts"
canonical: "https://test.abhinandan.one/node-sdk-agent-accounts"
markdown_url: "https://test.abhinandan.one/node-sdk-agent-accounts.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "Node.js SDK"
description: "Create an agent account without an API key using client.agent.createAccount, then upgrade it to a developer account with claimStart and claimVerify."
keywords: ["client.agent.createAccount", "claimStart", "claimVerify", "agent account", "email-claim flow", "AgentResource"]
last_modified: "2026-08-11T18:54:50.077661+00:00"
published_at: "2026-08-11T18:54:49.899492+00:00"
source_files:
  - "sdk-node/src/api/index.ts"
sections:
  - {anchor: "create-an-agent-account", title: "Create an agent account"}
  - {anchor: "step-construct-an-unauthenticated-client", title: "Construct an unauthenticated client"}
  - {anchor: "step-call-clientagentcreateaccount", title: "Call client.agent.createAccount"}
  - {anchor: "step-store-the-api-key-and-start-sending", title: "Store the API key and start sending"}
  - {anchor: "upgrade-to-a-developer-account-email-claim-flow", title: "Upgrade to a developer account (email-claim flow)"}
  - {anchor: "step-start-the-claim", title: "Start the claim"}
  - {anchor: "step-confirm-the-verification-code", title: "Confirm the verification code"}
  - {anchor: "step-verify-the-upgrade", title: "Verify the upgrade"}
  - {anchor: "doing-this-from-the-cli", title: "Doing this from the CLI"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# Agent Accounts

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.

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

> **Tip:** Building 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.

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

```typescript
import { createPrimitiveClient } from "@primitivedotdev/sdk/api";

const client = createPrimitiveClient({});
```

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

```typescript
import { createPrimitiveClient } from "@primitivedotdev/sdk/api";

const client = createPrimitiveClient({});
const account = await client.agent.createAccount({});
```

### 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`:

```typescript
import primitive from "@primitivedotdev/sdk";

const agentClient = primitive.client({ apiKey: agentApiKey });

await agentClient.reply(email, "Thank you for your email.");
```

> **Warning:** The `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.

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

```typescript
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. 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.

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

### 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](https://test.abhinandan.one/node-sdk-api-client/node-sdk-account-resource.md) if you need to confirm the new plan programmatically.

> **Tip:** If 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>

## Doing this from the CLI

Run [`primitive agent-upgrade`](https://test.abhinandan.one/cli-agent-upgrade.md), 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.