JWT Tokens

SpitShake uses JSON Web Tokens (JWT) to authenticate embedded signing forms and template builders. Tokens are generated server-side, scoped to a specific resource (submitter or template), and passed to the frontend embed components.

Tokens authenticate the JSON routes under /api/embed only. Embed the signing form with the submitter’s signing link (embed_src); the form ignores a token. The token-based builder page (data-token on <docuseal-builder>) is not available yet.

Overview

Property	Value
Algorithm	HS256 (HMAC-SHA256)
Default expiration	1 hour (general), 4 hours (form), 4 hours (builder)
Signing key	A per-account key held by SpitShake. It is never shared, so tokens come only from the token endpoint.
Token endpoint	`POST /api/embed/token`

Token types

SpitShake issues two types of embed tokens, each scoped by the aud (audience) claim.

Form tokens

Form tokens authenticate a signing session for a specific submitter. The sub claim contains the submitter ID, and the sid claim contains the submission ID. Full JWT claims:

{
  "sub": "142",
  "iss": "spitshake",
  "aud": "form",
  "sid": "89",
  "aid": "1",
  "iat": 1744195920,
  "exp": 1744210320,
  "opts": {
    "allow_to_resubmit": false,
    "with_title": true,
    "with_send_copy_button": true,
    "with_download_button": true
  }
}

Claim reference:

Claim	Type	Description
`sub`	string	Submitter ID. Identifies which signer this token is for.
`iss`	string	Issuer. Always `"spitshake"`.
`aud`	string	Audience. `"form"` for signing form tokens.
`sid`	string	Submission ID. The parent submission this submitter belongs to.
`aid`	string	Account ID. The SpitShake account that owns this submission.
`iat`	integer	Issued at. Unix timestamp when the token was generated.
`exp`	integer	Expiration. Unix timestamp when the token expires. Default: 4 hours after `iat`.
`opts.allow_to_resubmit`	boolean	Whether the signer can resubmit after completing.
`opts.with_title`	boolean	Whether to show the template title in the form.
`opts.with_send_copy_button`	boolean	Whether to show the “Send a copy” button.
`opts.with_download_button`	boolean	Whether to show the download button on the completion screen.

Builder tokens

Builder tokens authenticate access to the template editor for a specific template. The sub claim contains the template ID. Full JWT claims:

{
  "sub": "15",
  "iss": "spitshake",
  "aud": "builder",
  "aid": "1",
  "iat": 1744195920,
  "exp": 1744210320,
  "opts": {
    "autosave": true,
    "preview": true,
    "fields": []
  }
}

Claim reference:

Claim	Type	Description
`sub`	string	Template ID. Identifies which template the builder will load.
`iss`	string	Issuer. Always `"spitshake"`.
`aud`	string	Audience. `"builder"` for template builder tokens.
`aid`	string	Account ID. The SpitShake account that owns this template.
`iat`	integer	Issued at. Unix timestamp when the token was generated.
`exp`	integer	Expiration. Unix timestamp when the token expires. Default: 4 hours after `iat`.
`opts.autosave`	boolean	Whether the builder auto-saves changes.
`opts.preview`	boolean	Whether to show the document preview panel.
`opts.fields`	array	Pre-defined field definitions. Empty array means all field types are available.

When opts.fields is populated, it contains field definition objects:

{
  "sub": "15",
  "iss": "spitshake",
  "aud": "builder",
  "aid": "1",
  "iat": 1744195920,
  "exp": 1744210320,
  "opts": {
    "autosave": true,
    "preview": true,
    "fields": [
      {"name": "Full Name", "type": "text", "role": "Recipient", "required": true},
      {"name": "Signature", "type": "signature", "role": "Recipient", "required": true},
      {"name": "Date Signed", "type": "date", "role": "Recipient", "required": true},
      {"name": "Agreed to Terms", "type": "checkbox", "role": "Recipient", "required": true}
    ]
  }
}

Expiration defaults

Constant	Duration	Description
`DEFAULT_EXPIRATION`	1 hour	General-purpose token lifetime
`FORM_EXPIRATION`	4 hours	Signing form token lifetime
`BUILDER_EXPIRATION`	4 hours	Template builder token lifetime

Tokens are validated on every request. An expired token returns a 401 Unauthorized response with:

{
  "error": "token_expired",
  "message": "The embed token has expired. Generate a new token via POST /api/embed/token.",
  "expired_at": "2026-04-08T18:12:00.000Z"
}

Generating tokens via the API

Use POST /api/embed/token to generate embed tokens. Authenticate with your API token in the X-Auth-Token header.

Generate a form token

curl -X POST https://your-app.com/api/embed/token \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "form",
    "submitter_id": 142,
    "submission_id": 89,
    "options": {
      "allow_to_resubmit": false,
      "with_title": true,
      "with_send_copy_button": true,
      "with_download_button": true
    }
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNDIiLCJpc3MiOiJkb2N1dHJ1c3QiLCJhdWQiOiJmb3JtIiwic2lkIjoiODkiLCJhaWQiOiIxIiwiaWF0IjoxNzQ0MTk1OTIwLCJleHAiOjE3NDQyMTAzMjAsIm9wdHMiOnsiYWxsb3dfdG9fcmVzdWJtaXQiOmZhbHNlLCJ3aXRoX3RpdGxlIjp0cnVlLCJ3aXRoX3NlbmRfY29weV9idXR0b24iOnRydWUsIndpdGhfZG93bmxvYWRfYnV0dG9uIjp0cnVlfX0.Xq2nJ8vGhW4kP9mR",
  "expires_at": "2026-04-08T18:12:00.000Z",
  "audience": "form",
  "submitter_id": 142,
  "submission_id": 89
}

Generate a builder token

curl -X POST https://your-app.com/api/embed/token \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "builder",
    "template_id": 15,
    "options": {
      "autosave": true,
      "preview": true,
      "fields": [
        {"name": "Full Name", "type": "text", "role": "Recipient", "required": true},
        {"name": "Signature", "type": "signature", "role": "Recipient", "required": true},
        {"name": "Date Signed", "type": "date", "role": "Recipient", "required": true},
        {"name": "Agreed to Terms", "type": "checkbox", "role": "Recipient", "required": true}
      ]
    }
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNSIsImlzcyI6ImRvY3V0cnVzdCIsImF1ZCI6ImJ1aWxkZXIiLCJhaWQiOiIxIiwiaWF0IjoxNzQ0MTk1OTIwLCJleHAiOjE3NDQyMTAzMjAsIm9wdHMiOnsiYXV0b3NhdmUiOnRydWUsInByZXZpZXciOnRydWUsImZpZWxkcyI6W3sibmFtZSI6IkZ1bGwgTmFtZSIsInR5cGUiOiJ0ZXh0Iiwicm9sZSI6IlJlY2lwaWVudCIsInJlcXVpcmVkIjp0cnVlfSx7Im5hbWUiOiJTaWduYXR1cmUiLCJ0eXBlIjoic2lnbmF0dXJlIiwicm9sZSI6IlJlY2lwaWVudCIsInJlcXVpcmVkIjp0cnVlfSx7Im5hbWUiOiJEYXRlIFNpZ25lZCIsInR5cGUiOiJkYXRlIiwicm9sZSI6IlJlY2lwaWVudCIsInJlcXVpcmVkIjp0cnVlfSx7Im5hbWUiOiJBZ3JlZWQgdG8gVGVybXMiLCJ0eXBlIjoiY2hlY2tib3giLCJyb2xlIjoiUmVjaXBpZW50IiwicmVxdWlyZWQiOnRydWV9XX19.abc123",
  "expires_at": "2026-04-08T18:12:00.000Z",
  "audience": "builder",
  "template_id": 15
}

Security best practices

Request tokens from your backend

POST /api/embed/token needs your API token, so call it from your server and pass only the resulting embed token to the browser. Never put the API token in browser code.

Mint a token per session

Form and builder tokens last 4 hours. Request a fresh one each time you render the embed instead of storing one.

Scope tokens to specific resources

Each token should be scoped to exactly one submitter (form) or one template (builder). Never create tokens that grant access to multiple resources. The sub claim enforces this scoping.

Token types are not interchangeable

SpitShake checks the aud claim: a form token is rejected on the template routes and a builder token on the signing routes. A form token also opens only the submission it was minted for. A builder token reads its template; edits go through PUT /api/templates/{id}.

Do not embed tokens in URLs

Avoid passing JWT tokens as URL query parameters. URLs are logged in server access logs, browser history, and proxy logs. Instead, pass tokens via data-token attributes or JavaScript configuration objects.

<!-- WRONG: Token in URL (logged everywhere) -->
<iframe src="https://your-app.com/embed?token=eyJ..."></iframe>

<!-- RIGHT: Token in data attribute -->
<docuseal-builder data-token="eyJ..."></docuseal-builder>

Token flow diagram

The typical token flow for embedding:

Backend generates token

Your server calls POST /api/embed/token with the submitter/template ID and desired options.

Token sent to frontend

Your backend returns the token to the browser, either as part of an HTML page render or via an AJAX response.

Frontend passes token to embed

The token is set as a data-token attribute on the web component, or passed to SpitShake.mount() / SpitShake.mountBuilder().

Embed validates token

The SpitShake iframe receives the token, validates the signature and expiration, and loads the appropriate resource (form or builder).

Token expires

After the configured expiration time, the token is no longer valid. If the user’s session is still active, your backend should generate a fresh token.

Troubleshooting

Response	Cause	Fix
`401` `Token expired`	The token is past its `exp`	Request a new token
`401` `Invalid token: ...`	Bad signature, wrong token type for the route (`aud`), or wrong issuer	Request a token of the right `type` from `POST /api/embed/token`
`401` `Account not found`	The token’s `aid` matches no account	Request a new token
`404` `Not found`	The submission is not the one the form token was minted for	Use the submission ID the token was requested with
`422` `already_completed`	Saving a field after the signer completed	Nothing to save; the document is final
`422` `declined` / `expired`	Saving a field for a signer who declined or whose link expired	Nothing to save
`422` `complete_on_signing_page`	Calling the complete route	The signer completes in the embedded signing page
`422` `update_via_templates_api`	Updating a template with a builder token	Use `PUT /api/templates/{id}` with an API token
`403` `Insufficient scope` on `POST /api/embed/token`	A scoped API token lacks the scope for that token type	`submissions:write` for a form token, `templates:write` for a builder token

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

JWT Tokens

JWT Tokens

Overview

Token types

Form tokens

Builder tokens

Expiration defaults

Generating tokens via the API

Generate a form token

Generate a builder token

Security best practices

Token flow diagram

Troubleshooting

​JWT Tokens

​Overview

​Token types

​Form tokens

​Builder tokens

​Expiration defaults

​Generating tokens via the API

​Generate a form token

​Generate a builder token

​Security best practices

​Token flow diagram

​Troubleshooting

JWT Tokens

Overview

Token types

Form tokens

Builder tokens

Expiration defaults

Generating tokens via the API

Generate a form token

Generate a builder token

Security best practices

Token flow diagram

Troubleshooting