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

Property	Behavior
Scope	Each key belongs to exactly one organization and can only see and modify that organization's resources.
Ownership	A key belongs to the organization, not to the person who created it. It keeps working when that person leaves the organization or deletes their account. Who created or revoked a key is recorded in the organization's audit log.
Role	A key carries an organization role: `ADMIN` or `MEMBER`. Keys can never be `OWNER`. `ADMIN` unlocks template management, PDF asset uploads, direct signing-process creation, online documents and webhooks, and sees every signing process in the organization. `MEMBER` covers reads and starting signings from a published template, and sees only the signing processes that key created itself. On Enterprise a key can instead carry one of the organization's custom roles (`customRoleId` when the key is created in the dashboard): it may then do exactly what that role allows. When the key is created, its role must stay within the permissions of the person creating it, and only owners and admins create or revoke an `ADMIN` key; after that the key follows its role, so editing the role changes every key that carries it. A custom role cannot be deleted while working keys carry it: create replacement keys with another role and revoke these first. A role with webhook rights also sees every process, since webhooks receive every process event.
Storage	Only 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.
Expiry	Optional. A key can be created with an `expiresAt` timestamp; after that moment it stops authenticating. Keys without an expiry live until revoked.
Revocation	Immediate. Revoking a key in the dashboard rejects all subsequent requests made with it.

Managing keys

Key creation, listing and revocation require a logged-in user session in the SmartDocs dashboard: requests authenticated with an API key are refused for all three. This is deliberate. A leaked key can never mint fresh keys for itself, see which other keys exist, or revoke them, so revoking it always ends the exposure. The dashboard list shows metadata only (name, prefix, role, expiry), never the secret key material.

To rotate a key:

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

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

What a key cannot do

A key acts for the organization, never as a person. Anything that needs a person is refused:

account endpoints (/api/v1/auth/*: profile, sessions, password) answer 403;
self-signing (dispatchMode: "CURRENT_USER") answers 400, and a signer linked to a team member cannot be opened in kiosk mode with a key;
granting or refusing an approval step answers 403: an approval is the linked member's own decision;
inviting and removing members, changing roles, organization settings, billing and API keys are dashboard-only.

Members

Some requests name a team member: a signer linked to a member (linkedUserId) and an identity check recorded with a key (performedByUserId). A key looks the ids up with GET /api/v1/members, which lists every member with their userId, name, email, role and, on Enterprise, customRole (the organization's own role they hold, or null). It is read-only and needs the members.view permission, like the member list in the dashboard: an ADMIN key has it, a MEMBER key gets 403, and a custom role has it when the role includes it.

curl https://api.smartdocs.de/api/v1/members \
  -H "X-API-Key: sdk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

What a key creates

A key's records name the key instead of a person. A signing process started with a key has createdByUserId: null, createdByApiKeyId set to the key's id and createdByApiKey.name set to its name, and its audit events carry actorType: "API_KEY". No outcome email goes out for such a process; subscribe to webhooks to learn when it completes or is declined.

To record an in-person identity check with a key (POST /api/v1/signing-processes/{id}/signers/{signerId}/identity-proof), send the member who checked the signer's ID:

{ "performedByUserId": "3f0c6a52-4d1e-4b8f-9a61-0b7d2f7c9e14" }

Take the id from GET /api/v1/members; it must belong to a current member of the organization (422 otherwise). The evidence names that member as the one who checked, plus the key the record came through.

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.