Authentication
Every request carries a bearer token. The token also decides which organization it acts on: you never pass a tenant id yourself.
Bearer tokens
Send your token in the Authorization header on every request:
Authorization: Bearer sig_live_1a2b3c4d.…A complete request looks like this:
curl 'https://api.sign.quathos.com/api/v1/envelopes' \
-H "Authorization: Bearer $QUATHOS_SIGN_TOKEN"Keep secrets server-side
Live and test tokens
Every token carries an environment label in its prefix — sig_live_… or sig_test_… — chosen at creation and fixed afterwards. There is a single base URL, and a token is only accepted with the prefix it was issued with.
A test token is not a sandbox
sig_test_ token emails real signers and consumes credits exactly like a live one. Use the label to keep integration and production credentials apart, and send to addresses you control while you integrate.Creating a token
Tokens are created from the dashboard, under Developer → API tokens. Choose the environment label and the scopes it needs, then copy the secret.
Issuing a token requires a plan that includes the API (Growth or above) or an active API trial; otherwise the request returns 403 plan_feature_required:api. A token issued during the trial expires when the trial ends, unless the organization moves to a plan that includes the API first. Every other token is valid until you revoke it.
Shown once
Scopes
A token only reaches what its scopes allow. Grant the least you need — a token that just sends envelopes doesn’t need documents:write. A missing scope returns 403 with the scope’s name in detail, for example envelopes:send.
| Scope | Type | Description |
|---|---|---|
| documents:read | scope | List and download documents. |
| documents:write | scope | Upload documents. |
| envelopes:read | scope | Read envelopes, evidence and dossiers. |
| envelopes:write | scope | Create envelopes, add participants and fields. |
| envelopes:send | scope | Send envelopes and remind participants. |
| envelopes:cancel | scope | Cancel an envelope in progress. |
| templates:read | scope | List and read templates. |
| templates:write | scope | Create, update and apply templates — including bulk send. |
| proofs:read | scope | List proofs of existence and download their receipts. |
| proofs:write | scope | Register proofs of existence. |
| labels:read | scope | List labels. |
| labels:write | scope | Create and edit labels. |
| signatures:read | scope | Read signature records. |
| signatures:validate | scope | Validate signatures and document hashes. |
| audit:read | scope | Read the audit trail. |
| webhooks:manage | scope | Manage webhook endpoints and deliveries. |
| integrations:manage | scope | Manage cloud storage connectors (Google Drive / OneDrive). |
| billing:read | scope | Read credit balance, usage and plan (read-only). |
Idempotency
Write requests accept an Idempotency-Key header — a unique value (a UUID works well) per logical operation. Retrying with the same key and the same payload returns the original result instead of creating a duplicate. Reusing a key with a different payload returns 409 idempotency_key_reused_with_different_payload.
Idempotency-Key: 5c1f8b2e-9d4a-4f7c-8b1e-2a6f0c3d5e7aBase URL
All endpoints live under a single versioned prefix:
https://api.sign.quathos.com/api/v1