---
title: "Start agent account signup"
method: POST
path: "/agent/signup/start"
tags: ["Agent"]
---

# Start agent account signup

`POST /agent/signup/start`

Starts an agent-native signup session. `signup_code` is optional;
omit it to sign up without one. The API creates a pending signup
session, sends an email verification code, and returns an opaque
signup token used by the resend and verify steps. This endpoint
does not require an API key.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `email` string, email, required
  - `signup_code` string — Optional signup code. Omit if you do not have one.
  - `terms_accepted` true, required — Must be true to confirm acceptance of Primitive's Terms of Service and Privacy Policy
  - `device_name` string — Human-readable device name used for the created agent OAuth session
  - `metadata` object — Optional client metadata stored with the signup session; serialized JSON must be 2048 bytes or fewer

## Response `201`

Agent signup session created and verification email sent

- object
  - `success` true, required
  - `data` object, required
    - `signup_token` string, required — Opaque token used to verify or resend the pending agent signup
    - `email` string, email, required
    - `expires_in` integer, required — Seconds until the pending signup expires
    - `resend_after` integer, required — Minimum seconds before requesting another verification email
    - `verification_code_length` integer, required — Number of digits in the emailed verification code

## Other responses

- `400` — Invalid request parameters
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/primitive/apis/primitive-api.md) · [All operations](https://skmtc.net/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/primitive/primitive-api/versions/c2299d28022c/schema)