> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API-account activation and sandbox claims

> Current OpenAPI routes, implementation boundaries, and runtime prerequisites.

> The checked-in Go OpenAPI and public `batchrelay` CLI define the management
> routes and commands below. This is source-contract and CLI-help evidence, not
> proof that a deployed API has its management session, Clerk verification,
> Convex activation adapter, or Stripe configuration enabled.

API keys remain the credential for product operations. The OpenAPI management
routes require a `managementSession`, and the CLI provides the public browser
entry point:

```bash theme={null}
batchrelay auth login
batchrelay auth status
batchrelay auth logout
```

Never put management tokens, anonymous session tokens, claim codes, or Stripe
setup URLs in profile JSON, diagnostics, or command output.

## Claim sandbox work

An anonymous Test Mode bearer session creates a one-time claim code, then an
authorized management session submits that code to its chosen account. The
source code's OpenAPI contract is:

```text theme={null}
POST /v1/anonymous-sessions/current/claim-codes
POST /v1/api-accounts/{account_id}/sandbox-claim
```

The first route requires the anonymous bearer token and an idempotency key; it
returns a write-only `code` and `expires_at`. The second requires a management
session, an idempotency key, and `{ "claim_code": "..." }`. It returns the
account record, not the code.

The local Convex activation module has a durable, single-use claim design for
eligible Test workspace manifests, form drafts, catalog drafts, and studio
grants. It expressly excludes sandbox orders, provider submissions, API keys,
billing records, and credentials. The Go-to-Convex runtime adapter still must
be configured and deployed before this is an available customer workflow.
Retries for the same destination are designed to be idempotent; a redemption
for another destination must fail.

The CLI commands use explicit account IDs, stable idempotency keys, and JSON
request primitives. `sandbox claim-code` reads the saved anonymous session;
`sandbox claim` uses the signed-in management session.

```bash theme={null}
batchrelay sandbox claim-code --idempotency-key claim-code-20260829
batchrelay sandbox claim acct_example \
  --file claim.json --idempotency-key claim-20260829
```

`claim.json` contains the OpenAPI `SandboxClaimRequest`, for example
`{ "claim_code": "..." }`. The CLI deliberately does not print a second
credential as a convenience argument.

## OpenAPI management routes

```text theme={null}
GET  /v1/api-accounts
POST /v1/api-accounts
GET  /v1/api-accounts/{account_id}
GET  /v1/api-accounts/{account_id}/activation
POST /v1/api-accounts/{account_id}/agreements/{agreement_id}/accept
POST /v1/api-accounts/{account_id}/billing/setup-sessions
POST /v1/api-accounts/{account_id}/activate
```

`POST /v1/api-accounts` accepts `owner_type` (`individual` or `studio`) and a
`studio_id` only for a studio owner. Agreement acceptance accepts
`{ "version": "..." }`. Billing setup starts a Stripe-hosted setup session;
Batch Relay does not accept card data.

The matching CLI uses generic, file-backed request primitives rather than
inventing a parallel flag surface:

```bash theme={null}
batchrelay accounts create --file account.json
batchrelay accounts get acct_example
batchrelay accounts list
batchrelay accounts activation status acct_example
batchrelay accounts activation accept acct_example terms \
  --file agreement.json --idempotency-key terms-20260829
batchrelay accounts billing setup acct_example --file billing-setup.json
batchrelay accounts activation activate acct_example \
  --idempotency-key activation-20260829
```

`account.json` is `CreateAPIAccountRequest` (`owner_type`, and `studio_id` for
a studio account); `agreement.json` is `AgreementAcceptance` (`version`). Use
`batchrelay <group> <command> --help` for the currently pinned command syntax.

The current OpenAPI `APIAccountActivation` response contains `account_id`,
`status`, `agreements_current`, and `billing_ready`. It does **not** yet expose
the Convex module's detailed `missing_steps` list, nor does it define a
`live_activation_required` error. Do not build a client dependency on either
until the Go adapter, OpenAPI, and deployed API are updated together.

The local activation boundary records versioned policy ID/document-hash
acceptance with server time and actor, and requires current agreements, active
billing/default payment method, account readiness, and studio readiness before
switching the default environment to Live. The server-side Clerk OAuth verifier
and Stripe billing activation are still fail-closed/not deployed: the presence
of CLI commands or OpenAPI operations does not make a management token,
payment-method setup, or Live activation available. Those remain trusted Go
service boundaries, not Convex work.