Keys and authentication
Every request carries one API key. The key decides which organization, which environment and which actions.
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.
How do I authenticate a request?
Send your API key in the Authorization header as a Bearer token on every request.
Authorization: Bearer sw_test_...The API never accepts the SignWren session cookie, so a signed-in browser can't call it by accident. A missing, unknown or revoked key is 401 UNAUTHENTICATED. Keep keys on your server; never put one in a web page or a mobile app.
What's the difference between sandbox and live keys?
A sandbox key (sw_test_) only sees and makes sandbox envelopes, and a live key (sw_live_) only sees and makes live ones. The two environments belong to the same organization but never see each other's envelopes, webhook endpoints or delivery logs. Live keys need a plan that includes the API (Pro or Business); sandbox keys are on every plan, Free included.
Who can make a key, and what does it act as?
Owners and admins make keys in Settings under API keys, and each key is shown once. A key acts as the member who made it, with that member's current role, narrowed by the key's scopes, so if the member's role changes, so does what the key can do. Every action is written to the envelope's audit trail with the key's name.
Which scopes are there?
Give each key only the scopes its job needs; a call outside them is 403 SCOPE_REQUIRED with the scope named.
| Scope | Allows |
|---|---|
envelopes:read | Read envelopes, their status, audit trail and files |
envelopes:write | Upload documents; create, change, send, remind and void envelopes |
templates:read | Read your account templates and start envelopes from them (with envelopes:write) |
templates:write | Change account templates (not used yet) |
webhooks:manage | Add, change and delete webhook endpoints, and read their delivery log |
How do I rotate or revoke a key?
Roll a key in Settings to get a new one while the old one keeps working for an overlap you choose, from none up to 7 days; deploy the new key, then let the old one lapse. Revoking stops a key within a minute. Each new key, roll and revoke is recorded with who did it.
Why do I get 404 for something that exists?
Anything that belongs to another organization, or to the other environment, answers 404 NOT_FOUND, never 403. That way a key can't learn whether an id exists somewhere else. If you see 404 for an envelope you can open in the app, check that the key and the envelope are in the same environment.
What ids does the API use?
Every id has a type prefix: env_ for envelopes, doc_ documents, rcp_ recipients, fld_ fields, tpl_ templates, whk_ webhook endpoints and whd_ webhook deliveries. Treat them as opaque strings.
Last checked against the API spec on .