Preview. This API will change in v1.0.0. Breaking changes are announced in the release notes with migration steps before they apply, unless a security or legal issue needs an immediate change; then we announce it there as soon as we can.
Authentication
Send your key in the Authorization header of every request:
Authorization: Bearer sk_live_...
- Production keys start with
sk_live_and sandbox keys withsk_test_, followed by 48 hexadecimal characters. - DocuShield stores only a SHA-256 hash of each key. The full key is shown once, when you create it. If you lose it, revoke it and create a new one.
- A key acts as an admin of your organisation. Keys cannot be limited to certain actions yet, so keep them on your servers, never in a browser or a mobile app.
- An admin revokes a key on the API Keys page in the app. A revoked key is refused from the next request on.
POST /verifyneeds no key.
A missing, unknown or revoked key returns status 401 with the error shape described in Errors.
Sandbox and production
Sandbox key (sk_test_) | Production key (sk_live_) | |
|---|---|---|
GET /ebl lists | sandbox records | production records, including documents issued in the app |
POST /ebl files | a sandbox record | a production record |
Everything else is shared by both kinds of key: reading one record by its id, its history, webhooks and API keys. A webhook receives the events of sandbox and production records alike, and the payload does not say which kind of record it is. To tell them apart, read the record with GET /ebl/{id} and check its isSandbox field.
So a sandbox key is not isolated from production: it can read a production record by its id, manage webhooks and create a production key. Protect it as you would a production key.