API keys: scopes, expiry, IP allowlists and test mode
Create API keys safely: choose scopes, set an expiry, limit by IP address, and use test keys that never reach a real inbox.
An API key lets your software call SignSpry as you. Give each integration its own key, tick only the scopes it needs, set an expiry, and (if you can) pin it to your servers' IP addresses.
Where keys live
Open the account menu and choose API & webhooks, then Keys & webhooks. The REST API is part of the plans that include it (the Team plan lists it; check Plan & billing). Any signed-in user on such a plan can create keys. A key acts as the person who created it, so envelopes it creates belong to that person.
Create a key
- Click + Create key.
- Type a Key name (up to 60 characters), for example
production. - Choose Live or Test. The mode is fixed for the life of the key.
- Choose when it expires: 30 days, 90 days (pre-selected), 1 year or Never.
- Tick the Scopes (below). You must pick at least one.
- Optionally list Allowed IP addresses, one per line.
- Click Create key, then copy the key straight away.
The table afterwards shows the key's first 16 characters, its scopes, expiry, allowed addresses, the last address it was used from and when it was last used.
Scopes
| Scope | Lets the key |
|---|---|
envelopes:read | list envelopes, read status, audit trails and sealed documents |
envelopes:write | create, send, remind, void, and mint signing and embed links |
templates:read | read templates |
account:read | read plan and usage |
The two envelopes scopes are ticked by default. A call outside the key's scopes returns 403 with a message naming the missing scope. A key marked full access (legacy) was made before scopes existed and can do everything; replace it with a narrower one.
Expiry and rotation
An expired key returns 401 ("this API key expired on …"). SignSpry emails the key's owner once, about a week before the date, and the date turns red in the table for the last seven days. Keys cannot be extended, so rotate them:
- Create a replacement key with the same scopes.
- Deploy it to your integration.
- Revoke the old key.
IP allowlist
Enter IPv4 or IPv6 addresses, or CIDR ranges such as 198.51.100.0/24, one per line or separated by commas (up to 20). Leave it empty to allow any address. A call from anywhere else returns 403 ("this API key is not allowed from …").
Test keys
A Test key starts with sk_test_ and shows a sandbox pill. Its envelopes send no email or text. See The sandbox.
Limits and errors
| Status | Meaning |
|---|---|
| 401 | missing, invalid, expired or revoked key |
| 402 | your plan does not include the API |
| 403 | outside the key's scopes, or not an allowed IP address |
| 429 | more than 120 requests a minute on this key |
Revoking and the record
Revoke works immediately. Keys of deactivated users stop working too. Admin → Security log records every key created (with scopes, expiry and allowed addresses) and revoked, and every webhook endpoint added or removed.