SignWren

Sandbox and mock server

Two ways to test: the sandbox, which is the real API with test envelopes, and a mock you run yourself.

Status. The SignWren API is opening in stages and may not be on your account yet. If Settings shows an API keys section, you can make sandbox keys now; live keys come with the Pro and Business plans. SignWren is an electronic signature app for small businesses; it is not a law firm and does not give legal advice.

What is the sandbox?

The sandbox is a second environment of your own SignWren organization, reached with a sw_test_ key, where envelopes behave like live ones but can never become valid signed agreements. You go through the whole flow: upload, send, the signer's consent and signing steps, sealing, the certificate, webhooks and downloads.

How is a sandbox envelope different from a live one?

  • Every page of the document carries the watermark "SANDBOX: not valid for signature", and the certificate of completion is titled "Sandbox test".
  • The finished PDF is sealed with a test certificate, never SignWren's production seal.
  • Email is only sent to members of your account with a verified address. Mail for anyone else is kept in the sandbox outbox in the app, where owners and admins can read it and open the signing link.
  • Sandbox envelopes don't count toward your plan's usage. They have their own allowance of 100 a month.
  • Sandbox data is deleted 30 days after it was made.
  • Webhook events from the sandbox carry "environment": "sandbox" and "livemode": false.

Are sandbox signatures valid?

No. A signature in the sandbox is a test, and the watermark and test seal say so on the document itself. Don't use the sandbox to sign anything real, and don't send real customers sandbox envelopes; switch to a live key for that.

What is the mock server for?

The mock server answers every operation in the OpenAPI file with that operation's example, so you can test your client with no key, no network and no data. It behaves like the API where a client would notice: it wants a well-formed key, sends Request-Id and rate-limit headers, uses the same error body, replays an Idempotency-Key and refuses one reused with a different body, echoes ids from the URL, and serves PDFs with an ETag. It stores nothing and statuses never change, so use the sandbox for end-to-end tests.

It ships with the Node SDK. Run it on its own for any language:

npx signwren-mock --port 4010
# SignWren mock API from the OpenAPI spec: http://127.0.0.1:4010/v1

Or start it inside a Node test, where it can also be told to fail:

import { SignWren, RateLimitError } from '@signwren/sdk';
import { startMockServer } from '@signwren/sdk/testing';

const mock = await startMockServer();
const sw = new SignWren({ apiKey: 'sw_test_' + 'x'.repeat(43), baseUrl: mock.url });

const envelope = await sw.envelopes.get('env_7d1e0c2b9a8f4e3d8c7b6a5f4e3d2c1b'); // the spec's example

mock.fail({ status: 429, retryAfter: 1 });          // the next request is rate limited
await sw.envelopes.list();                          // the SDK waits a second and tries again

console.log(mock.requests.map((r) => r.operationId));
await mock.close();

Any client can force one error with a request header:

curl http://127.0.0.1:4010/v1/envelopes \
  -H "Authorization: Bearer sw_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "SignWren-Mock-Status: 503"

How does SignWren test its own SDK?

The Node SDK's unit tests run against this mock, and its end-to-end test drives a sandbox envelope from upload to the sealed PDF against the real API, running on a test database. The MCP server is tested the same two ways.

Last checked against the API spec on .