Test with a sandbox key

A sandbox key works on sample data instead of your organization's records, so you can build and test an integration before it touches them. It uses the same base URL, POST /v2/oauth/token, endpoints and response shapes as a live key, so code written against the sandbox runs unchanged with a live key. A sandbox request never reads or writes your organization's records. Brellium never processes a sandbox document, and the sandbox emails nobody and never reads a file you upload.

Create a sandbox key

On the API keys page of the dashboard, click Create key and enter a name. Choose Sandbox under Environment (Production is the default), then copy the Client ID, Client secret and Audience. The dashboard shows the secret only when you create the key. Rotate secret in the key's row menu issues a new one, also shown once.

The page needs API platform access, which an administrator grants in Brellium. Without it, API keys shows "No access to manage API keys". To get access, ask an administrator or contact Brellium support.

A sandbox key carries a Sandbox badge on the API keys page. Its environment is fixed at creation, and Rotate secret does not change it. To use the live environment, create a second key.

Mint a sandbox token

Mint a token as you would with a live key, but set audience to https://api.brellium.dev/sandbox (Authenticate with OAuth2 client credentials).

curl "https://api.brellium.com/v2/oauth/token" \
  --request POST \
  --header "Content-Type: application/json" \
  --data "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$BRELLIUM_SANDBOX_CLIENT_ID\",
    \"client_secret\": \"$BRELLIUM_SANDBOX_CLIENT_SECRET\",
    \"audience\": \"https://api.brellium.dev/sandbox\"
  }"

const res = await fetch("https://api.brellium.com/v2/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.BRELLIUM_SANDBOX_CLIENT_ID,
    client_secret: process.env.BRELLIUM_SANDBOX_CLIENT_SECRET,
    audience: "https://api.brellium.dev/sandbox",
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`HTTP ${res.status}: ${JSON.stringify(body)}`);
console.log(body);

Send the token as Authorization: Bearer <token> to the same base URL. There is no sandbox host and no header to set, because the token's audience picks the environment. A sandbox key mints tokens only for the sandbox audience and a live key only for the live one; the token endpoint refuses the other audience with an access_denied body.

The two sandbox-specific 401 codes, ENVIRONMENT_MISMATCH and SANDBOX_UNAVAILABLE, are listed in Rate limits and errors. For a walkthrough from key to audit, see Test end to end with sandbox credentials.

Sample data

Your first sandbox request seeds the sample data, which uses the same ids as the examples in the guides and the API reference:

Differences from live

Reads, filters, pagination, validation and errors behave the same as with a live key. In the sandbox, the next request already sees a write; with a live key, lists can take a few seconds to include a new or changed record. The other differences are in what happens after a write:

The audit the sandbox creates for an upload is the sample audit with new ids, so its responses are the same for every upload. In the sandbox, every uploaded document gets an audit, except a zip and any document still without an audit when its batch expires. With a live key, Brellium decides which documents are audited.

Sandbox and live keys both need your organization set up for document uploads. Without that setup, POST /v2/documents returns 404 ORG_NOT_FOUND; contact Brellium support. Every other endpoint works without it.

Document status schedule

The sandbox moves documents through their statuses on a fixed schedule instead of processing them.

curl "https://api.brellium.com/v2/documents" \
  --request POST \
  --header "Authorization: Bearer $SANDBOX_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "documents": [
      { "filename": "session-note.pdf", "content_type": "application/pdf" },
      { "filename": "attachment.pdf", "content_type": "application/pdf" }
    ],
    "grouping": "group"
  }'

const res = await fetch("https://api.brellium.com/v2/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SANDBOX_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [
      { filename: "session-note.pdf", content_type: "application/pdf" },
      { filename: "attachment.pdf", content_type: "application/pdf" },
    ],
    grouping: "group",
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`HTTP ${res.status}: ${JSON.stringify(body.error)}`);
console.log(body);

import BrelliumClient from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.SANDBOX_ACCESS_TOKEN });

const documents = await client.documents.create({
  documents: [
    { filename: "session-note.pdf", content_type: "application/pdf" },
    { filename: "attachment.pdf", content_type: "application/pdf" },
  ],
  grouping: "group",
});
console.log(documents);

import os

from brellium_api_client import BrelliumClient

client = BrelliumClient(o_auth2=os.environ["SANDBOX_ACCESS_TOKEN"])

documents = client.documents.create(
    documents=[
        {"filename": "session-note.pdf", "content_type": "application/pdf"},
        {"filename": "attachment.pdf", "content_type": "application/pdf"},
    ],
    grouping="group",
)
print(documents.to_json())

As with a live key, if any file of a batch is still missing 24 hours after the batch was created, the whole batch expires (Incomplete batches expire after 24 hours). Its pending_upload documents become upload_expired and its external_id values are released, so you can send the batch again.

Zips

The API validates and creates a zip as it does with a live key, but the sandbox never unpacks it. Once its file arrives, the zip document moves to extracted with metadata.archive set to { "grouping": "<your grouping>", "entries": 0, "skipped": 0 }. The sandbox creates no documents from the files in the zip, and no audit follows.

Limits

The sandbox holds at most 5,000 records per resource per organization, and a create past that limit returns 409 SANDBOX_LIMIT. To make room, delete some users or email recipients, or reset the sandbox. A reset is the only way to clear documents and audits, which have no delete endpoint.

Your organization can send a burst of 100 requests, then 5 per second, shared by every key; the sandbox has a separate budget with the same limits. For the rate-limit headers and how to retry a 429, see Rate limits and errors.

Reset the sandbox

A POST to /v2/sandbox/reset with a sandbox token and no body deletes everything in your organization's sandbox, uploaded files included, and returns 204. The next request seeds the sample data again. The endpoint exists only in the sandbox and is not in the reference; with a live token it returns 404 NOT_FOUND.

Each organization has its own sandbox. Nothing in it is deleted on a schedule, so its records and files persist until you reset.

curl "https://api.brellium.com/v2/sandbox/reset" \
  --request POST \
  --header "Authorization: Bearer $SANDBOX_ACCESS_TOKEN"

const res = await fetch("https://api.brellium.com/v2/sandbox/reset", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SANDBOX_ACCESS_TOKEN}` },
});
if (!res.ok)
  throw new Error(
    `HTTP ${res.status}: ${JSON.stringify((await res.json()).error)}`,
  );
console.log(`HTTP ${res.status}`);

Next