Agent Accounts and Account Management API

Use the generated account operations to read your org's account record and fetch the webhook signing secret, alongside the client.agent lifecycle. Reach for this page when you need account-level data that the high-level send/reply/forward client doesn't expose.

The account operations are part of the generated API client, the OpenAPI-codegenerated surface exported from @primitivedotdev/sdk/api. Creating a zero-touch account and upgrading it is covered separately in Agent Accounts.

Fetch account details#

Call the generated getAccount operation with a PrimitiveApiClient, the host-aware authenticated request client, to read your org's account record.

import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";

const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
const result = await getAccount({ client: api.client });

console.log(result.data);

Every operation returns the server's { success, data } envelope. On a non-2xx response the generated client surfaces the error rather than throwing a plain Error; see Node.js SDK Errors for the PrimitiveApiError shape and how to read code, status, and requestId.

Fetch the webhook signing secret#

The secret used to verify the Primitive-Signature header comes from GET /account/webhook-secret, and it is a UTF-8 string you use as-is.

import { PrimitiveApiClient } from "@primitivedotdev/sdk/api";

const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
const response = await api.request("GET", "/account/webhook-secret");

console.log(response);

Once you have the secret, Webhook Signature Verification covers how it verifies the Primitive-Signature: t=<unix-seconds>,v1=<hex> header, including the 300-second replay tolerance.

Check inbox readiness#

Inbox readiness reports whether inbound mail can actually reach your webhook endpoint, which is worth checking right after account creation or a DNS change.

The CLI exposes this directly:

primitive inbox-status

See Inbox Setup and Status for the fields it reports (receiving readiness, processing readiness, domains, endpoints). Domain and route configuration itself is a platform concept covered in Primitive Functions and Recipient Routing; readiness reporting only tells you the current state, it does not configure anything.

Next steps#