Sandbox Testing

Two credentials, not one

Every call carries your usual sandbox X-Game-Secret-Key and a second header, X-Sandbox-Clock-Key. The second one exists because force-renewal genuinely charges a card: a leaked game secret should not also be a charge-on-demand button. Both are required on all four endpoints, and presenting one without the other is refused.

• The clock key is per title, and you issue it yourself from the sandbox developer API: GET /sandbox/api/dev/games/{game_id}/sandbox-clock-key, documented immediately below. A console screen for it is on the way; until it ships, that endpoint is how you get one.
• It is deliberately not retrievable with the game secret. The issuing endpoint authenticates with your developer dashboard session, never with X-Game-Secret-Key. If the game secret could fetch the clock key, the game secret would once again be sufficient on its own and the second factor would be decorative. That constraint is the entire reason this credential exists.
• It is a sandbox credential only. There is no production counterpart, because there is no production endpoint to present it to.
• Rotation has two modes and the difference matters. A routine rotation leaves the previous key working for a 7-day grace so a test run already in flight does not break; a leaked key needs the immediate mode, which revokes the old value on the spot. See the rotate endpoint below, and Partner Credentials & Key Handling.
• Server-side only. Never in a browser bundle, never in a repository, never in chat.

Getting and rotating your clock key

Two endpoints on the sandbox developer API, both authenticated with the dashboard session token your console login issues, Authorization: Bearer <token>, the same credential the dashboard's own pages use. The game secret is not accepted here and never will be; you must be signed in as the developer account that owns the title. Both live only on the sandbox service: calling them on production returns 409 SANDBOX_ONLY and issues nothing, because a production clock key could never authenticate anything.

DEV=https://sandbox.invo.network/sandbox/api/dev
GAME_ID=1234

# Reveal (mints on the first call). Dashboard session token, NOT the game secret.
curl -s "$DEV/games/$GAME_ID/sandbox-clock-key" \
  -H "Authorization: Bearer $INVO_DASHBOARD_TOKEN"

# → { "success": true, "game_id": 1234,
#     "header": "X-Sandbox-Clock-Key",
#     "sandbox_clock_key": "ivclk_…",
#     "issued": true, "newly_issued": true,
#     "rotated_at": "2026-08-14T11:02:57+00:00",
#     "previous_key_active": false, "previous_key_valid_until": null,
#     "note": "Send this in the X-Sandbox-Clock-Key header IN ADDITION to your …" }

export INVO_SANDBOX_CLOCK_KEY=ivclk_…

# Routine: new key now, old key valid for 7 more days.
curl -X POST "$DEV/games/$GAME_ID/sandbox-clock-key/rotate" \
  -H "Authorization: Bearer $INVO_DASHBOARD_TOKEN"

# LEAKED KEY: revoke the old value immediately, no grace.
curl -X POST "$DEV/games/$GAME_ID/sandbox-clock-key/rotate" \
  -H "Authorization: Bearer $INVO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immediate": true}'

Request body (optional)

Response (200)

{
  "status": "ok",
  "action": "advance-clock",
  "intervals": 1,
  "intervals_applied_to_window": 0,
  "window_moved": false,
  "window_already_elapsed": false,
  "before": { ...clock fields before... },
  "after": {
    "subscription_id": "SUB_1786012800_A1B2C3D4",
    "status": "active",
    "period_seq": 3,
    "current_period_start": "2026-09-13T09:14:22+00:00",
    "current_period_end": "2026-10-13T09:14:22+00:00",
    "next_charge_at": "2026-08-14T11:02:57+00:00",
    "trial_end": null,
    "cancel_at_period_end": false,
    "wallet_only": false,
    "has_payment_method": true,
    "amount_usd": "9.99"
  },
  "note": "The subscription is now due..."
}

before and after carry the same eleven clock fields, so you can diff exactly what the call changed.

Response (200)

{
  "status": "ok",
  "action": "force-renewal",
  "period_seq": 3,
  "attempt_no": 1,
  "amount_usd": "9.99",
  "amount_coins": "99.90",
  "engine_stats": { "renewed": 1 },
  "subscription": { ...clock fields after the run... }
}

engine_stats is the renewal engine's own counters for this one run, so a failed renewal is as legible as a successful one. Exactly one outcome counter is set, and it is one of renewed, declined, insufficient, auth_required, containment, ambiguous, settle_failed, errors, abandoned (the subscription was cancelled or ended under the claim, so nothing was charged and no retry was consumed) or refused_over_ceiling (the price failed the per-renewal ceiling; held, not dunned). periods_forgiven may appear alongside the outcome when the run had elapsed windows to catch up on. Treat any counter you did not expect as a real outcome rather than switching on a fixed set of two or three.

Which outcome you get is decided by the card on the subscription. Pick from the test cards above to steer it, or use force-failure when you want a specific outcome regardless of card.

Refusals are the two shared sets below: opening a renewal and all four endpoints.

Request body (optional)

Response (200)

{
  "status": "ok",
  "action": "force-failure",
  "period_seq": 3,
  "attempt_no": 2,
  "outcome": "card_declined",
  "failure_code": "card_declined",
  "retry_budget_used": 1,
  "retry_schedule_days": [2, 3, 2],
  "retries_remaining": 2,
  "containment_failure_code": "…",
  "subscription": { ...clock fields after the run... }
}

attempt_no and retry_budget_used are different numbers on purpose: not every failure consumes retry budget. Call this repeatedly to walk a subscription all the way to expired and verify your revocation path. containment_failure_code is echoed back so you can pass it as failure_code to reproduce the origin-containment branch: held rather than retried, exempt from the retry budget, and it never expires the member.

Refusals are the two shared sets below (this endpoint opens a real claim, so it can return every refusal in opening a renewal too), plus 400 INVALID_OUTCOME.

Response (200)

{
  "status": "ok",
  "action": "force-auth-challenge",
  "period_seq": 3,
  "attempt_no": 2,
  "auth_challenges_used": 1,
  "max_auth_challenges": 2,
  "downgraded_to_decline": false,
  "retry_budget_used": 0,
  "subscription": { ...clock fields after the run... }
}

Refusals are the two shared sets below (this endpoint opens a real claim, so it can return every refusal in opening a renewal too). AUTH_CHALLENGE_OPEN is the one to expect here: once a challenge object exists for the period, the next call is refused until it is completed or expires.

Refusals shared by the three that open a renewal

force-renewal, force-failure and force-auth-challenge all open a real claim (the same period record and attempt record the scheduled renewal opens) before they do anything else. So all three return every refusal below, not just the one that spends money. Write your handling once.

Refusals shared by all four