Create a sandbox API key
api_key.sandbox.create
Creates a sandbox API key limited to the actions available in this product. Use it for test traffic before going live. The secret appears once, in this response. The key lasts until you revoke it. A key made from a CLI login or agent token cannot run operations no agent may run, such as webhook.endpoint.create. The response lists those in browserKeyOnlyOperationIds. Callers: the founder's CLI login, or an agent token with keys:write, or a personal access token with keys:write.
POST /v1/sandbox-api-keys
Principal user_session. Idempotency required. Environment sandbox.
Input
| Field | In | Type | Description |
|---|---|---|---|
X-Hyperscale-Environment | header | sandbox | live | |
Idempotency-Key required | header | string | |
X-Hyperscale-Rehearsal | header | "true" | `true` runs the request through admission and execution, keeps nothing, and answers OperationRehearsal with 200 in place of the operation's own output. Needs a signed-in caller. Identity operations, such as sign-in, sessions, team members and agent grants, refuse it with invalid_request. |
tenantId required | body | string | Organization tenant ID |
productId required | body | string | Hyperscale product ID |
name required | body | string | |
capabilities | body | identity | accounts | internal_transfers | products | activity | usage | billing | webhooks | verification[] | Narrow the key to this subset of the product's enabled capabilities; operations outside them are refused. Omit for the default: full access to everything enabled on the product. |
replace | body | boolean | Revoke the active key with this name in the same call |
Request sample
curl --request POST 'https://hyperscale0.ai/v1/sandbox-api-keys' \
--header "Authorization: Bearer $HYPERSCALE_API_KEY" \
--header 'X-Hyperscale-Environment: sandbox' \
--header "Idempotency-Key: $(uuidgen)" \
--header 'Content-Type: application/json' \
--data-raw '{"tenantId":"ten_sandbox_fb76ff74228aa14d","productId":"prd_sandbox_97c43dbc8495d7ca","name":"Desk & Key server"}'Errors
| Code | HTTP | Cause |
|---|---|---|
agent_approval_denied | 403 | A human denied the agent's proposed operation. |
agent_approval_required | 202 | An agent proposed a protected live operation. |
agent_reason_required | 400 | An agent sent a change without saying why, or the reason is shorter than 8 or longer than 280 characters. |
agent_result_already_delivered | 409 | A caller already claimed this approval's one-time result. |
csrf_token_invalid | 403 | A browser session mutation did not carry a current Hyperscale CSRF token. |
environment_mismatch | 403 | The session was issued for sandbox or live and the request targets the other environment. |
idempotency_conflict | 409 | The request reused an Idempotency-Key for a different logical mutation. |
idempotency_required | 400 | The operation is a mutation and Hyperscale requires a replay key before executing it. |
internal_error | 500 | Hyperscale hit an unexpected server-side condition and hid internal implementation details from this audience. |
invalid_request | 400 | The request does not match the API reference. |
missing_required_permission | 403 | The signed-in member's current role does not grant the permission required for this operation. |
missing_required_scope | 403 | The credential is valid but does not grant one or more operation scopes. |
not_found | 404 | No Hyperscale route matched the requested path and method. |
rate_limited | 429 | The credential sent more than its limit in the current 60-second window: 600 requests per API key or session, 1,200 per IP address. Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (Unix seconds). |
request_body_too_large | 413 | The JSON request body exceeded Hyperscale's accepted payload size. |
resource_not_found | 404 | The requested resource does not exist in the credential's visible scope. |
state_conflict | 409 | The operation conflicts with the current durable state of the resource. |
state_constraint_failed | 422 | The request is syntactically valid but violates a business-state constraint. |
tenant_mismatch | 403 | The request mixed tenant-owned identifiers across tenant boundaries. |
tenant_not_found | 404 | The credential resolved to a tenant Hyperscale cannot find. |
unauthorized | 403 | The request did not include a valid Hyperscale bearer credential for this environment. |
agent_token_expired | 401 | The agent token is real, but its grant ended. A grant lasts 30 days, or 7 days unused. `details.expiresAt` holds the date in ISO 8601 and `details.agentName` names the agent. |
agent_token_replaced | 401 | The founder ran `hyperscale agent setup` again for this agent, which replaced this token with a newer one. `details.agentName` names the agent and `details.replacedAt` holds the date. |
capability_not_enabled | 400 | The key mint asked for a capability scope that includes capabilities this product does not have enabled (for live keys: live-enabled). No key was created. |
device_login_expired | 401 | The bearer is the founder's own device login from `hyperscale auth login`, not an agent token. Its access token lasts an hour and the CLI refreshes it; the login itself ends after 30 days, or 7 days unused. `details.expiresAt` holds when it ended in ISO 8601. |
instrument_instance_not_found | 404 | No record of this instrument matches the `instanceId` in this Product, company and environment. `details.instrumentId` and `details.instrumentInstanceId` name what was looked up. |
invalid_credentials | 401 | Hyperscale could not accept the account or credential request. Signup, login, and bearer authentication use one 401 for every case they reject, so the response exposes no credential-specific reason or registered-email verdict. The single exception is a key that is real but homed in the other environment: because the presented secret already matched a stored key, the message names the mismatch instead of leaving a working credential looking unknown. A bearer that matched nothing gets text that fits its prefix (an agent token, a refresh token, a personal access token, a session or no Hyperscale token at all), which says only what the caller sent, never whether a credential like it exists. |
operation_not_finalized | 409 | The operation in `details.operationId` has started but has no final receipt. It is still running, or its outcome is unknown after a failure past the point where it may have committed. `details.error` carries the underlying failure when there is one. |
product_not_found | 404 | No Product matches the `productId` in this tenant and environment, or a resource the request names belongs to a different Product than the API key's. A missing, foreign or ambiguous resource binding also reports this code. |
sandbox_environment_required | 400 | This operation runs only in sandbox. That covers Product creation and composition, enabling capabilities, composition-scoped API keys, rehearsal Products and provider webhook simulation. |
session_expired | 401 | The session behind this request has ended. A console session ends 30 days after sign-in, or after 12 hours with no request. An admin or customer session ends 24 hours after sign-in, or after 15 minutes with no request. A personal access token ends at the `expiresAt` set when it was created. |
session_required | 401 | This operation needs a person signed in through the browser or the `hyperscale` CLI. A Product API key cannot call it. The request carried no session, or its token matched no live session. |
session_revoked | 401 | The session or personal access token behind this request was ended before its expiry. Sign-out, `user.session.revoke`, a password reset, a role change, removal from the team, user suspension and `personal_access_token.revoke` all end sessions. |
tenant_status_forbidden | 409 | The company is suspended or closed, so every credential bound to it is refused, reads included. `details.tenantId` names the company. |