Sandbox Mode

How sk_test keys behave, simulated responses, and which endpoints are affected.

Sandbox Mode lets you test the public API without changing service, request, or invoice data. Create a Sandbox API key in API Center. Sandbox keys use the sk_test_ prefix.

Authentication And Access

Send the Sandbox API key as a Bearer token on every request.

Authorization: Bearer YOUR_TEST_API_KEY

Sandbox Mode does not bypass the API firewall. A restricted Sandbox key fails when its IP whitelist is empty or when the caller IP is not on the whitelist.

A Sandbox request updates the key’s Last Used time, uses the key’s rate limit, and creates an API log.

Simulated Operations

Endpoint	Required scope	Sandbox response
GET /api/v1/auth-check	Any valid key	Returns real broker and key metadata. Returns the real service count when permitted.
POST /api/v1/auth-check	services:write or admin:full	Confirms that the key has write access.
POST /api/v1/service-create	services:write or admin:full	Returns a generated request. With automatic approval, it also returns a generated active service and test credentials. With manual approval, it returns a simulated pending request. It does not create a record or provision a service.
GET /api/v1/services	services:read or admin:full	Returns one generated service, or an empty list when filters do not match. It applies status, search, modified_since, limit, and offset rules to the generated row. Test credentials are included only when include_credentials=true and the key has admin:full.
GET /api/v1/services/{service_number}	admin:full	Returns generated service details and test credentials. It echoes the numeric service number. It does not look up a service.
POST /api/v1/services/{service_number}/password	admin:full	Validates the request and reports a simulated password update. It can return a generated test password. It does not change a password or send an email.
POST /api/v1/services/{service_number}/upgrade	admin:full	Validates the requested plan and returns an accepted upgrade request. It uses Basic VPS as the simulated current plan. It does not change a plan.
POST /api/v1/services/{service_number}/downgrade	admin:full	Validates the requested plan and returns an accepted downgrade request. It uses Professional VPS as the simulated current plan. It does not change a plan.
POST /api/v1/services/{service_number}/cancel	admin:full	Validates the cancellation reason and returns an accepted cancellation request. It does not cancel a service.
GET /api/v1/requests	requests:read or admin:full	Returns one generated request, or an empty list when search or pagination does not match. It applies the accepted status, type, source, date, search, limit, and offset input rules. It does not read service request records.
POST /api/v1/requests/{request_id}/manage	requests:write or admin:full	Returns a simulated approval or denial. Approval returns a generated service number. Denial requires denial_reason. It does not change a request or create a service.
POST /api/v1/reports/services	reports:generate or admin:full	Returns fixed simulated totals and the normalized recipient count. It does not read service records, make a report file, or send email.
POST /api/v1/reports/invoices	reports:generate or admin:full	Returns fixed simulated invoice totals, the requested date range, and the normalized recipient count. It does not read invoices, make a report file, or send email.

Simulated business responses include mode: "test" and simulated: true. The auth-check response identifies the API key mode as test instead.

Identifier Formats

Sandbox Mode uses public identifiers only.

• Generated request IDs use REQ- and six digits, such as REQ-004219.
• Generated service numbers are nine-digit numbers.
• The request management path accepts REQ- followed by digits. Matching is not case-sensitive. The response uses uppercase REQ- and pads the number to at least six digits.
• Service paths accept a numeric service number.

A generated identifier is not stored. You cannot use it to test a later state change. For example, a create response does not add its service to the service list response.

Test Scenarios

Use the optional X-Test-Scenario header to test selected response paths. Header values are not case-sensitive. An unknown value uses the success scenario.

Header value	Result
Omit the header or use success	Returns the normal simulated success response.
validation_error	Returns HTTP 400 with code invalid_parameter and a simulated validation error.
server_error	Returns HTTP 500 with code server_error and a simulated server error.
nycservers_review	Returns HTTP 202 with request_status: "nycservers_review" for service creation, upgrades, downgrades, cancellations, and request approvals. Other simulated operations use their normal success response.

The endpoint validates its path, query, and body input before it applies a test scenario. A malformed request can therefore return a normal validation error instead of the selected scenario. A denial in the request management endpoint also uses the denial response before it applies nycservers_review.

Limitations

Sandbox Mode tests request structure, authentication, permissions, filters, and response handling. It does not test these live behaviors:

• Record ownership, record existence, or the current service state.
• Provisioning, upstream password changes, plan changes, and cancellations.
• Email delivery, report generation, or report attachments.
• Persistent state or workflows that use an identifier from an earlier response.
• Live data volumes. List endpoints return at most one generated row, and report totals are fixed.

Generated timestamps use the time of each request. Request IDs for service creation, plan changes, and cancellations can change between requests. Use a Live key only when you are ready to run a real operation.