Best practices
Security Best Practices
Secure a SignatureAPI integration: store and rotate API keys, limit Dashboard access, verify webhooks, and keep personal data out of metadata and logs.
Most of an integration’s security comes down to three secrets: your API keys, your webhook signing secrets, and the links SignatureAPI gives you (ceremony URLs and deliverable URLs). This page covers each, plus the data you send.
API Keys
An API key can do everything in its mode for your account: create, read, cancel and delete envelopes, and download signed documents. Treat it like a database password.
- Keep it on your server. Never put a key in a web page, a mobile app or any code that runs on a user’s device. Your server calls SignatureAPI and hands the browser only what it needs, such as a ceremony URL.
- Store it as a secret. Read it from an environment variable or your platform’s secret manager. Keep
.envfiles out of version control. - Use one live key per application. Live keys can be created and deleted on their own, so one key per service or environment lets you revoke one without touching the others.
- Rotate it. Rotate on a schedule, and right away if a key may have leaked. Create the new live key, deploy it, then delete the old one, so no request fails in between. See Rotating API keys.
- Keep it out of logs. Don’t log request headers, and redact
X-API-Keyin any HTTP client debug output.
Dashboard Access
Everyone on your team gets their own Dashboard login and a role. Give each person the narrowest role that fits their work. Only some roles can manage API keys, webhooks and senders in live mode. See User roles, and remove people who leave.
Webhooks
- Verify every delivery. Check the signature on the raw body before you act on the event. See Verify webhook signatures.
- Use HTTPS for every endpoint URL.
- Keep the signing secret as safe as an API key. Each endpoint has its own, and test and live endpoints never share one.
- Restrict by IP if your endpoint sits behind a firewall: allow only the source IPs.
- Don’t trust the payload alone for important decisions. Fetch the envelope from the API before you act, for example before you release goods on
envelope.completed.
Links That Grant Access
- Ceremony URLs are bearer credentials: anyone who has one can open the ceremony. Don’t log them or store them on a device. Ask your server for a fresh URL instead. See Ceremony URL.
- Deliverable URLs are, by default, pre-signed: they need no authentication until they expire after 1 hour. Download the file on your server and serve it from your own storage, rather than passing the URL to users.
- Embedded ceremonies shown in an iframe load only inside the page origins you list in
embeddable_in. List only the origins that show it. See Embedded signing.
Personal Data
- Keep sensitive data out of
metadataandtopics. Both appear in API responses, andmetadatais repeated in every webhook payload asdata.envelope_metadata. Store your own record ID there, and keep the rest in your database. - Send only the documents and fields the envelope needs. Everything you send is stored with the envelope until you delete it. See Data retention and deletion.
- Test with synthetic data. Test mode sends no email, so made-up names and addresses work everywhere. See Test your integration.