API keys and authentication for e-signature APIs
API key authentication is how an e-signature API confirms which developer account a given request belongs to, without requiring a full login flow for every call. You generate a key once, from your account, and then include it with every API request so the service knows who's calling and what they're allowed to do.
How Esignapi's API keys work
Esignapi uses a single header-based API key per request, sent as x-api-key. The key itself is structured as two parts separated by a period — a key ID and a key secret — generated together when you create the key from your account settings. The server validates the secret against what it stored (hashed, not in plain text) when you created the key, and rejects the request if it doesn't match or the key has been revoked.
Where the API key goes
Every authenticated request includes the key in its headers:
x-api-key: your_key_id.your_key_secret
This is simpler than OAuth-style token exchanges, which makes sense for a server-to-server integration where there's no end user logging in through a browser — your own backend is the thing calling the API, using a credential you control directly.
Creating and managing keys
API keys are created from your account's API settings, where you can also see when a key was last used and revoke it if it's no longer needed or you suspect it's been exposed. Revoking a key takes effect immediately — any requests sent with a revoked key are rejected the same way an invalid key would be.
Keeping an API key secure
- Never embed it in client-side code. An API key sent directly from a browser or mobile app is visible to anyone who inspects network traffic or the app's bundled code. Keep API calls on your own backend, where the key stays server-side.
- Don't commit it to version control. Treat it the same way you'd treat a database password — in an environment variable or a secrets manager, not hardcoded in a file that ends up in a git repository.
- Revoke and rotate keys that may have been exposed. If a key ends up in a log file, a support ticket, or a public repository by accident, revoke it and generate a new one rather than hoping it goes unnoticed.
- Use a distinct key per environment if your workflow supports it, so a key used in a staging or test environment is clearly separate from the one used in production.
What happens with an invalid or missing key
A request sent without a valid x-api-key header is rejected before any of the request's actual content (the document, the signers, the fields) is processed — authentication happens first. This means a typo in the key, or sending the key secret without its key ID prefix, fails in the same way an entirely wrong key would: the request is rejected rather than partially processed.
Does an API key limit what account data it can access?
A key is tied to the developer account (and, depending on your account setup, a specific workspace within it) that created it — it doesn't give access to other accounts' documents or signature requests. If your integration needs to act on behalf of multiple separate customer accounts, that typically means managing a separate key per account rather than sharing one key across unrelated accounts.
API keys and rate limits
Rate limiting is applied per account, not per individual API key, so if you're generating multiple keys for the same account (one for a script, one for a server, for example) they still share the same underlying rate limit rather than each getting an independent allowance. See Rate limits and best practices for e-signature APIs for the specifics.
Why there's no OAuth flow for this kind of integration
OAuth is designed for situations where a third-party application needs limited, user-granted access to someone else's account — think "Sign in with Google." A server-to-server e-signature integration is a different situation: it's your own backend, using your own account's credentials, to perform an action you're already authorized to do. A static API key is the simpler, more appropriate mechanism for that case, which is why most API-first products in this space, including Esignapi, use one rather than a full OAuth handshake.
What the key ID and key secret are each used for
The two-part structure — a key ID followed by a key secret — mirrors a pattern used by many API-first platforms: the key ID is effectively a public identifier for which key is being used (useful for displaying "last used" information or for revoking a specific key without needing the secret itself), while the key secret is the actual sensitive credential that proves the request is authorized. This split matters operationally: your account settings can safely show you a list of key IDs and when each was last used, without ever needing to display or store the secret in a retrievable form after it was first generated.
What happens the first and only time you see the full key
When you create a new API key, the full key (ID and secret together) is shown to you once. After that, only the key ID and metadata like last-used time remain visible — the secret itself isn't stored anywhere you can retrieve later, since the server stores a hash of it rather than the plain value. If you lose the secret before saving it somewhere secure, the practical fix is to revoke that key and generate a new one, rather than trying to recover the original.
Testing authentication before building your full integration
Before writing any real integration code, it's worth confirming your key works at all with the simplest possible request — a basic status-check call using a tool like curl, with just the x-api-key header set, to confirm you get a valid response rather than a 401. This isolates authentication issues from anything else that might go wrong later in a more complex integration, so if something fails afterward you already know the key itself isn't the problem.
Get your API key
Esignapi's account settings let you generate an API key and see working authentication examples in multiple languages.
Frequently asked questions
Can I have more than one API key on the same account?
Yes, you can generate multiple keys — useful for separating keys by environment or by which part of your system is calling the API, while still sharing the same account-level rate limit and permissions.
What should I do if I accidentally commit an API key to a public repository?
Revoke the exposed key immediately from your account settings and generate a new one. Revocation takes effect right away, so any further use of the old key will be rejected.
Does the API key expire automatically?
Keys don't expire on a fixed schedule by default — they remain valid until you revoke them yourself, which is part of why keeping them secure and revoking unused ones proactively matters.
Is the API key the same thing as my account password?
No — your account password is used to log into the dashboard through the browser; the API key is a separate credential specifically for programmatic access, and the two aren't interchangeable.
Can I restrict an API key to only certain actions, like reading but not creating requests?
Esignapi's API keys are account-level credentials rather than scoped to individual permissions — if you need to separate read access from write access in your own system, that's something to enforce in your own integration layer rather than through the key itself.