Skip to content
Subnoto Logo Subnoto Documentation

API Sandbox

A sandbox workspace lets you exercise the full Subnoto workflow without the side effects of a real send. In sandbox mode, envelope sending is simulated: no invitation emails go out, no credits are consumed, and signed PDFs use a test certificate rather than a production one.

Sandbox mode is designed for integration testing - try your API flows, embedded signing, and webhooks before you go live with customers.

What is different in sandbox mode?

Section titled “What is different in sandbox mode?”

No invitation emails

When you send an envelope, recipients do not receive invitation emails. Signing links are still created so you can test flows manually or via the API.

No credit usage

Webapp sends do not consume SES credits. Public API sends do not consume API credits.

Test signatures

Completed documents are signed with a development certificate. External PDF verifiers will not treat them as legally binding production signatures.

SMS verification simulated

SMS OTP requests succeed but no text message is sent and no OTP is stored. Use email verification or other flows when testing SMS-gated signing in sandbox.

Prerequisites

Section titled “Prerequisites”

Sandbox mode can only be enabled or disabled through the public API. The webapp does not expose a sandbox toggle in Settings.

Section titled “Recommended setup”

Create a dedicated workspace for testing and keep your production workspaces in normal mode. Do not enable sandbox on your default workspace unless you intend to use it only for tests.

Enable sandbox mode

Section titled “Enable sandbox mode”

  1. Create a test workspace (if you do not have one yet)

    Terminal window
    curl -X POST http://your-proxy:8080/public/workspace/create \
      -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Integration tests",
        "colorHex": "#6366F1"
      }'

    Save the workspace.uuid from the response. New workspaces start with "sandbox": false.

  2. Turn on sandbox mode

    Terminal window
    curl -X POST http://your-proxy:8080/public/workspace/update \
      -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workspaceUuid": "your-workspace-uuid",
        "sandbox": true
      }'

  3. Confirm the flag

    List or get the workspace and check that "sandbox": true:

    Terminal window
    curl -X POST http://your-proxy:8080/public/workspace/list \
      -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'

  4. Run your tests

    Create envelopes, send them, open signing links, trigger webhooks, and download results - all within this workspace without charging credits or emailing real recipients.

  5. Disable sandbox when done

    Terminal window
    curl -X POST http://your-proxy:8080/public/workspace/update \
      -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workspaceUuid": "your-workspace-uuid",
        "sandbox": false
      }'

Using the TypeScript SDK (connects directly to https://enclave.subnoto.com):

const { data, error } = await client.POST("/public/workspace/update", {
    body: {
        workspaceUuid: "your-workspace-uuid",
        sandbox: true
    }
});

Using the webapp in a sandbox workspace

Section titled “Using the webapp in a sandbox workspace”

Team members can use a sandbox workspace in the webapp like any other workspace: upload documents, add recipients, send envelopes, and track progress. The same sandbox rules apply when sending from the webapp.

A few webapp behaviours differ:

  • Sign in person is not available in sandbox workspaces. See Sign in Person for the production flow.
  • There is currently no sandbox badge in the webapp interface. Check the sandbox field via the API if you need to confirm which workspaces are in test mode.

What still behaves normally

Section titled “What still behaves normally”
  • Workspace members, roles, and document isolation work the same as in a normal workspace. See How to isolate documents with workspaces.
  • Email OTP for signing is still sent in sandbox mode (only SMS OTP is simulated).
  • Webhooks fire on envelope events as usual, so you can test your automation end-to-end.
  • Automatic reminders may still send real emails if configured on the envelope. Prefer turning reminders off on test envelopes, or use recipient addresses you control.

Troubleshooting

Section titled “Troubleshooting”
Section titled “Related resources”

Summary: Create a dedicated test workspace, set sandbox: true via the public API, run your integration tests without emails or credits, then set sandbox: false before production use.