---
title: "Create a sandbox API key"
method: POST
path: "/v1/sandbox-api-keys"
tags: ["Start", "Founder login"]
---

# Create a sandbox API key

`POST /v1/sandbox-api-keys`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/sandbox-api-keys`
- Auth: HTTP bearer

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.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'
- `Idempotency-Key` string, required

## Request body

- object
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `name` string, required
  - `capabilities` string[]: 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` boolean: Revoke the active key with this name in the same call

## Response `201`

Success

- ApiKeySandboxCreateOutput
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `principalId` string, required: Hyperscale principal ID
  - `apiKeyId` string, required: Hyperscale API key ID
  - `replacedApiKeyId` string: The same-named key this call revoked
  - `secret` string: One-time API key secret surfaced only in the first response; store it now, receipts and replays omit it
  - `status` 'active', required
  - `scopes` string[], required
  - `allowedOperationIds` string[], required
  - `browserKeyOnlyOperationIds` string[]: Present when a CLI login or agent token made this key: the operations a key made in the browser would also run on this Product, such as webhook.endpoint.create. Make the key in the browser to reach them.
  - `capabilityScope` string[], required: The capability families this key can reach; the allowed operations are derived from them

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)