Register an agent through HTTPS with a recoverable identity

What registration actually creates

POST /v0/agent/register is a public HTTPS entry point that needs neither a bearer token nor a human email address. It creates a new Free workspace, default project, inbox and restricted workspace API key. It does not create a console user or attach the agent to an existing customer workspace. This is useful for a new agent that needs an address to receive work before a human decides whether to grant broader authority. Registration itself contacts no mail, phone, browser, model, app or payment provider and sends no verification email.

Persist the request identity first

Before calling, generate an unguessable Idempotency-Key containing 32 to 256 letters, digits, underscores or hyphens. Save it in private storage together with the exact username. The username must contain 3 to 40 letters, digits or hyphens and begin and end with a letter or digit. The registration secret is a recovery credential because an identical replay can retrieve the original API key. Do not place it in a source file, URL, shared transcript or ordinary request log. Saving it after the network request leaves a recovery gap.

curl --fail-with-body --silent --show-error \
  https://api.lupin.sh/v0/agent/register \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $LUPIN_REGISTRATION_KEY" \
  -d '{"username":"research-agent"}' \
  -o "$LUPIN_PRIVATE_STATE/registration.pending.json"

Handle creation and replay separately

A new identity returns HTTP 201. Repeating the identical request with the saved secret returns HTTP 200 and the original workspace and key. Read the organization_id, project_id, inbox_id and email fields rather than predicting their values from the username. The request example writes to a pending file: require a successful HTTP exit, validate api_key, organization_id and inbox_id with a JSON parser, then atomically rename that file before marking your agent provisioned. Never replace your original secret or a valid saved registration with an error response. A timeout means the response was lost or delayed; it does not prove creation failed. Repeat the same request identity instead of inventing another username or secret. A 409 idempotency_conflict means the secret is already associated with different request content.

Use the initial capabilities honestly

The returned key can receive and read email and create drafts. Outgoing email, additional inbox creation, new key issuance and paid resources are disabled by its permissions and workspace policy. The initial workspace has overages disabled and a zero spending setting. Those restrictions are part of the bootstrap boundary, so do not use trial sends to discover whether the boundary still exists. Inspect your own inbox and create reviewable drafts instead. Human claim later associates ownership with a verified console session while preserving the original bootstrap key restrictions.

Respect admission and recovery failures

New registrations are limited to five per IP group per UTC day and 100 globally; IPv6 addresses share their /64 quota group. Honor Retry-After on a 429 rather than rotating addresses or secrets. A 503 registration_unavailable or persistence_failed requires preserving the original request identity and retrying later. A revoked original key produces signup_key_revoked and is not restored by replay. The next useful step after success is GET /v0/auth/me followed by an inbox read with the returned credential, then secure storage and a separate human claim when broader ownership is required.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin autonomous registration ↗Checked 2026-11-05
• Lupin authentication ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.