Recover agent registration with the original saved secret

Recovery begins before the first request

The autonomous registration Idempotency-Key is a secret recovery handle, not disposable request metadata. Generate an unguessable value with 32 to 256 permitted characters and save it together with the exact username before calling POST /v0/agent/register. If the network response disappears after creation, that saved pair is how the agent retrieves the original workspace and key. A random value generated only in memory does not provide recoverability after a crash. Never put the secret in an ordinary HTTP log, repository or public task transcript.

Replay the identical request

Send the same username and header value after a timeout. The server hashes the creation secret and canonical request identity, looks for an existing durable registration and returns that identity on an exact replay. New creation returns 201; replay returns 200. Your client should accept both as successful responses, validate required fields and preserve the returned resource IDs. Do not interpret 200 as evidence that a new workspace was created. The purpose of replay is to recover the same identity rather than allocate another inbox whenever a worker restarts.

Do not overwrite good state with errors

Write the response to a private pending file or transactional record. Require a successful HTTP result and validate api_key, organization_id, project_id, inbox_id and email before atomically promoting it to active credential state. An error response can also be valid JSON, so successful JSON parsing alone is insufficient. Keep an existing valid registration intact until replacement data is proven valid. If the stored secret and username disagree with another local record, stop and reconcile the records instead of choosing whichever value makes the request succeed.

Distinguish conflict from revocation

A 409 idempotency_conflict means that secret is bound to a different request. Restore the original username rather than changing the secret to escape the conflict. signup_key_revoked means the original credential has been revoked; replay does not restore it. registration_resource_changed means an expected original resource, such as the inbox, is no longer present. These are identity lifecycle events, not generic transient failures. Use an existing authorized owner or workspace recovery path to investigate, preserving the original registration record for a deliberate decision.

Honor admission failures without identity churn

A 429 applies creation admission limits and includes Retry-After. A 503 registration_unavailable or persistence_failed means safe completion is unavailable; preserve the same identity and retry later. IPv6 privacy-address rotation does not create a fresh quota because /64 groups share the daily limit. Existing exact replays recover their durable registration rather than consuming another new identity. Do not rotate IPs, usernames or secrets to evade the five-per-IP-group or 100-global daily creation limits.

Build a recovery fixture

Test a local sequence that creates an identity, drops the response, restarts the client and replays the original request. Assert the same organization, project, inbox and API key return. Add conflicting-body and revoked-key cases and ensure neither causes hidden replacement registration. Your next operational step is to verify that your secret store persists the retry secret before any production registration call can begin.

Sources & verification

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

• Lupin registration recovery ↗Checked 2026-11-05
• Lupin conventions ↗Checked 2026-11-05

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