Your server mints a short-lived session with a secret key, your page frames it with a 1.5 KB SDK, and your users sign without leaving your product. Build the whole integration on free test keys first.
An embed starts as a session your server mints. Your page frames the URL it gets back, and the frame talks to your code over a pinned postMessage channel.
POST /embed_sessions with your secret key, naming the document and the origin of the page that will frame it. You get back an id and a URL that expires.
Hand the URL to @gingerdocs/embed. It frames the signing experience on our origin, pins the origin and session id on both ends, and hands your code typed events.
SDK events are UX signals — hide a spinner, show a confirmation. Provision on the signed document.completed webhook; every event stays readable for 90 days.
const res = await fetch('https://api.gingerdocs.com/api/v1/embed_sessions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GINGERDOCS_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'signing',
document_id: documentId,
host_origin: 'https://app.example.com',
}),
})
const { id, url } = await res.json()import { mount } from '@gingerdocs/embed'
const embed = mount('#signing', { url, sessionId: id })
embed.on('ready', () => hideLoader())
embed.on('completed', () => showConfirmation())
embed.on('session_expired', async () => {
const fresh = await refetchSession()
embed.reload(fresh.url, { sessionId: fresh.id })
})import { GingerDocsEmbed } from '@gingerdocs/react'
<GingerDocsEmbed
url={session.url}
sessionId={session.id}
onEvent={event => event.type === 'completed' && showConfirmation()}
/>Pass the URL verbatim: its fragment carries the session credential, and its query carries what our edge uses to decide who may frame the page.
Every embed is a session your server mints. Its kind and mode decide what the person in the frame can do — and the server enforces it on every request, not just in the UI.
One signer, one document, inside your page. No email round-trip, no redirect off your site.
Template-driven creation for one of your own users, without exposing an editor.
The same editor the GingerDocs app ships, running on your domain.
A fourth mode, read_only, shows a finished document or a template with nothing to act on — a viewer you can drop into your own UI.
Everything under https://api.gingerdocs.com/api/v1, authenticated with a bearer API key. Create a user, upload a document, send it, and read what happened — in four calls, from any language.
curl https://api.gingerdocs.com/api/v1/account \
-H "Authorization: Bearer gd_sk_test_YOUR_KEY"{
"environment": "test",
"scopes": ["documents", "templates", "users", "embed", "webhooks"],
"plan": { "key": "free", "limit": 30, "used": 12, "remaining": 18 },
"defaults": { "email_delivery": "platform" }
}The people in your product that documents belong to, keyed by your own external_id.
Upload a PDF or instantiate a template, name the signer, follow the status, download the signed copy.
Signature, initials, text, date, and checkbox fields, placed in normalised page coordinates.
List, share, and instantiate templates authored in the app or in an advanced workspace.
We email the signer, or you deliver the signing link yourself and we send nothing at all.
Register HTTPS endpoints, read the delivery log, and replay any event from the 90-day log.
v1 has exactly one signer per document — no recipient lists, no signing order, no hand-off.
Signing is the easy half. The rest — delivery, verification, retries, branding, languages — comes with the platform.
HMAC-SHA256-signed deliveries with retries and a delivery log. Every event stays readable for 90 days through the events API, so nothing is lost while your endpoint is down.
Test keys work on every plan. Output is watermarked and not legally binding, nothing counts against your plan, a test endpoint can simulate the signature so CI can assert COMPLETED, and test data is purged after 90 days.
Pass theme.primary_color when you mint and the frame's buttons, links, and focus rings follow it. An Expand control lets a narrow sidebar embed take over the viewport and hand it back.
Per account or per send, choose whether GingerDocs emails the signer with your branding or your product does — in which case we send nothing and hand you the signing URL.
When you deliver the link or admit a signer through an embedded session, the Certificate of Completion names your legal entity as the verifying party — the responsibility you accept in the Integrator Terms.
Signing and workspace frames ship in English, Japanese, Korean, German, Spanish, and French. Set the locale on the session or the mount; a signer can switch from the frame's own menu.
The SDK does one thing: it frames the session URL, pins the origin and session id on both ends of the postMessage channel, and hands your code typed events. You can read it in one sitting.
Framework-free. mount(), on(), reload(), unmount() — and the Expand protocol, if you would rather build the iframe yourself.
View on GitHubA thin React component around the core package: one onEvent handler for every event, safe to pass inline.
View on GitHubGuides from your first key to a signed document, an endpoint reference you can call from, and the OpenAPI 3.1 contract the API is validated against.
Developer Mode and test keys are available on every plan, including Free. The whole integration — create, send, sign, webhook, download — works in the test environment.
Get a test keyEverything in Pro with the same 1,000 document uploads a month, plus live API keys, embedded signing on your registered domains, and signed webhooks.
See the Developer planSign up for free, switch on Developer Mode under Settings → Developer, and make your first API call in minutes. No credit card required.