Skip to main content

Test API requests safely

The public API Reference is currently read-only. No approved remote sandbox host and tenant are configured, so Test Request stays hidden and every interactive request is rejected before the browser can send it.

The localhost-only live-read mode is an explicit exception for approved GET operations. Do not place an API key, session token, customer identifier, or response body in documentation examples or browser diagnostics.

Try the local live-read mode​

When the documentation is served from 127.0.0.1 or localhost, the embedded Scalar panel enables Test Request directly inside Docusaurus. It sends allowlisted GET requests to https://api.ordering.co, with an editable project that defaults to orderingv1. The real response appears under Response → Body.

Start with GET /configs, GET /countries, or GET /ai/agents/{agent_id}/templates. Other operations can display the panel, but Send remains blocked unless the method and path are part of the local live-read allowlist. Requests may return production data. Use only projects and credentials you are authorized to access.

The gray text shown in the credential field is an OpenAPI placeholder, not a stored key. Leave the field empty when the endpoint does not require one.

An API key entered in Scalar stays in the current document memory because persistAuth remains disabled. Reloading, navigating away, or selecting Clear credentials removes it.

What the sandbox mode will allow​

Sandbox testing can be enabled only after Ordering approves one non-production hostname and one disposable tenant. The first approved phase is limited to an explicit method + path allowlist within GET, HEAD, and OPTIONS. A GET label alone is not accepted as proof that an operation has no side effect. POST, PUT, PATCH, DELETE, request bodies, uploads, payments, webhooks, campaigns, messages, integrations, files, and administrative operations remain blocked.

When the gate is active, the API Reference shows:

  • SANDBOX — Requests do not affect production;
  • the exact destination hostname and tenant before a request;
  • a Clear credentials action;
  • request states for success, invalid input, 401, 403, 429, timeout, network/CORS failure, and server failure.

Use only your own approved sandbox credential. Scalar holds it in the current document memory with persistAuth: false; the documentation does not add a cookie or write the credential to local storage, session storage, a URL, analytics, or logs. Reloading, leaving the reference, restoring from browser history, or selecting Clear credentials destroys and recreates the Scalar session.

Why a CORS error is not a safety control​

CORS controls whether browser JavaScript can read a response. It does not prove that the API did not receive or execute a request. The browser guard therefore validates the final HTTPS origin, tenant, method, headers, body and redirect policy before calling fetch. The sandbox API must independently enforce its own authentication, CORS origin allowlist, rate limit, payload limit, observability redaction and data cleanup.

As verified on September 11, 2026, the production endpoint already responds to localhost with wildcard CORS and permits the documented authentication headers. This documentation branch does not change API CORS. The localhost transport therefore treats its exact origin, operation and method allowlist as a mandatory pre-fetch boundary rather than relying on CORS for safety.

Maintainer activation gate​

Do not enable the button from a browser flag or a one-file UI edit. A reviewed activation must provide all of the following together:

  1. Written authority for the sandbox hostname and disposable tenant.
  2. Synthetic fixtures and a verified reset/cleanup owner.
  3. A server-side rate limit and bounded request size.
  4. CORS restricted to https://docs.ordering.co and the specifically approved local development origins; production CORS must not change.
  5. Redacted logs that never record authorization values, request bodies or sensitive response headers.
  6. An update to src/apiReferenceSandboxPolicy.ts and the API Reference connect-src policy in worker/index.ts in the same reviewed change.
  7. A source-reviewed allowlist naming every permitted method and path, plus passing negative tests for production, unknown hosts, wrong tenants, mutations, bodies/uploads, credentials in URLs, redirects, timeouts and throttling.
  8. A separate opt-in certification against the approved sandbox. Hermetic tests run first and never contact an external API.

Until every item is verified, the required state is SCALAR_SANDBOX_BLOCKED.