SmartDocs API

Authentication

Every API request is authenticated with an organization API key. Keys start with the sdk_live_ prefix and can be sent in either of two ways — both are equivalent:

# Option 1: X-API-Key header
curl https://api.smartdocs.de/api/v1/templates \
  -H "X-API-Key: sdk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Option 2: Authorization Bearer header (the token must keep the sdk_live_ prefix)
curl https://api.smartdocs.de/api/v1/templates \
  -H "Authorization: Bearer sdk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Requests without valid credentials fail with 401 — that includes keys that are expired or have been revoked.

Key properties

PropertyBehavior
ScopeEach key belongs to exactly one organization and can only see and modify that organization's resources.
RoleA key carries an organization role: ADMIN or MEMBER. Keys can never be OWNER. ADMIN unlocks every endpoint — template management, PDF asset uploads, and direct signing-process creation. MEMBER covers reads and starting signings from a published template. A MEMBER key only sees signing processes created by the user who created the key; ADMIN keys see the whole organization's processes.
StorageOnly a SHA-256 hash of the key is stored at rest, plus a short display prefix for identification in the dashboard. The full key is shown exactly once, at creation — it cannot be retrieved again.
ExpiryOptional. A key can be created with an expiresAt timestamp; after that moment it stops authenticating. Keys without an expiry live until revoked.
RevocationImmediate. Revoking a key in the dashboard rejects all subsequent requests made with it.

Managing keys

Key creation and revocation require a logged-in user session in the SmartDocs dashboard — requests authenticated with an API key are explicitly refused for those operations. This is deliberate: a leaked key can never mint fresh keys for itself or revoke others, so revoking it always ends the exposure. Key listing (GET /api/v1/api-keys) is available to an ADMIN API key and returns metadata only — names, prefixes, roles, and expiry — never the secret key material.

To rotate a key:

  1. Create a new key in the dashboard (same role, or tighter).
  2. Deploy the new key to your integration and confirm traffic works.
  3. Revoke the old key.

Because both keys are valid during step 2, rotation requires no downtime.

Security best practices

  • Never hard-code keys. Load them from environment variables or a secret manager. Keep them out of source control, client-side code, and logs.
  • One key per integration. Give each service, environment, and vendor its own key so you can revoke one consumer without breaking the others — and so usage is attributable.
  • Use MEMBER where it suffices. If an integration only reads templates or checks signing status, a MEMBER key limits the blast radius of a leak.
  • Set expiresAt for short-lived access. Contractors, migrations, and one-off scripts should get keys that expire on their own instead of relying on someone remembering to revoke them.
  • Rotate on suspicion. If a key may have leaked, create a replacement and revoke the old key immediately — revocation takes effect on the next request.