Sandbox keys and rotation

This page is available only to a Merchant operating in its own home scope in sandbox. White Labels, Agents, selected downlines, and every live session neither see the menu nor call the route.

What the page may read

GET /v1/bo/sandbox?scope_id=<merchant UUID> returns secret-free metadata:

• the current credential UUID, sk_test prefix, and fixed deposits:read plus deposits:write scopes;
• server-owned creation and exact 90-day expiry timestamps;
• the singleton-slot revision, which must match the response ETag;
• a still-valid predecessor and its valid_until boundary when an overlap exists.

Plaintext, suffixes, digests, R2 references, ciphertext, and keyring metadata are structurally absent. The client discards the entire response if an unknown field crosses this closed boundary.

Choose a rotation policy

Choice	Effect
Immediate (overlap_seconds=0)	Revokes the current credential and any predecessor in the same commit. Use for a security event.
Five-minute overlap (overlap_seconds=300)	Activates the new credential immediately while the previous one remains valid until DB clock +5 minutes. Use for a planned rollout.

At most one predecessor can be active. A nested overlap returns 409 sandbox_overlap_active; an immediate rotation may collapse the chain without extending the old boundary.

Required UI flow

1. Read fresh metadata and retain credential.id, revision, and ETag.
2. Let the operator choose immediate or five minutes and confirm the reason.
3. Open a fresh OIDC popup from the click gesture and call POST /v1/bo/auth/step-up/sandbox. The proof binds the exact body bytes, revision, credential, scope, overlap, and idempotency key.
4. Accept only an exact-origin paygate:sandbox-step-up message. Its in-memory token starts with pgsba1..
5. Reuse the identical body bytes for POST /v1/bo/sandbox/rotate with Content-Type: application/json; charset=utf-8, If-Match, Idempotency-Key, X-PG-Step-Up-Token, and X-PG-BO-Client: 1.

The first successful execution reveals one sk_test_<43 base64url chars> secret. Copy it to a secret manager, then close the dialog. The UI clears plaintext on dialog close, navigation, and logout. There is no read-back or reveal endpoint.

Response lost after commit

Retrying the same idempotency key returns the original metadata with Idempotency-Replayed: true, secret_available=false, and secret=null. This prevents a second disclosure. If the first secret was not retained, rotate again with a new command.

Errors to handle

• 404 sandbox_credential_not_found — the session/scope is not exact Merchant sandbox or the slot changed;
• 409 sandbox_version_conflict — refetch metadata and ask the operator to review it;
• 409 sandbox_overlap_active — wait until valid_until or choose an immediate rotation with a new idempotency key;
• 401 step_up_required — start a fresh popup; never reuse the token;
• 428 mutation_precondition_required — If-Match is absent or malformed;
• 503 sandbox_rotation_unavailable — stop and retry with backoff; never generate a credential in the browser.

Preview is read-only and never simulates a successful rotation or generates a secret.