SignWith API authentication: API keys

Send the key as a Bearer token

Put the key in the Authorization header of every request:

Authorization: Bearer sw_live_3xAmPl3K3y...

A request without a valid key gets 401 unauthenticated. There is no other way to authenticate with the REST API: OAuth tokens are only for the MCP server, not for /api/v1.

Create and revoke keys

Create keys in SignWith under Settings → Developers, and revoke them there too. Each key belongs to the user who created it and acts with that user's permissions, so a key can only see the templates and signature requests its user can see.

Keep keys on your server. Anyone with a key can act as its user, so never put one in a web page, a mobile app or a public repository. To replace a key, create the new one, deploy it, then revoke the old one.

Live and test keys

The prefix tells you which environment a key acts on:

Both use the same base URL, https://app.signwith.co/api/v1. To check which environment, user and account a key belongs to, call GET /me:

curl https://app.signwith.co/api/v1/me \
  -H "Authorization: Bearer $SIGNWITH_API_KEY"

const response = await fetch('https://app.signwith.co/api/v1/me', {
  headers: {
    Authorization: `Bearer ${process.env.SIGNWITH_API_KEY}`,
  },
})

console.log(response.status, await response.json())

import os

import requests

response = requests.get(
    "https://app.signwith.co/api/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['SIGNWITH_API_KEY']}",
    },
)

print(response.status_code, response.json())

The response's environment is live or test, and api_key.permission is full or read.

Full-access and read-only keys

A full-access key can call every endpoint. A read-only key can call:

• any GET endpoint,
• POST /documents/verify, which checks a PDF without changing anything,
• POST /feedback, which sends feedback to the SignWith team.

Every other write with a read-only key returns 403 read_only_api_key. Use read-only keys for dashboards, reporting and anything else that only needs to look. Each endpoint in the API reference says which kind of key it needs.

Key expiry

A key can have an expiry date, shown as api_key.expires_at in GET /me (null if it never expires). After that date every request returns 401 api_key_expired, and you need a new key.

Authentication errors

All error codes are on the errors page.