Authentication

A sign_admin mints keys in Rutba Sign (Settings → Integrator API keys). The key is shown once, stored only as a salted hash, and revocable per key. Send it as a bearer token; the base URL is your instance’s own origin. The shared app host, app.sign.rutba.io, does not accept API key requests yet.

curl https://YOUR-INSTANCE/api/sign/v1/envelopes \
  -H "Authorization: Bearer sgk_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Mutual NDA"}'

Requests and responses are JSON; results arrive under a data key and errors as { error: { message } } with the usual status codes. An unknown key and a revoked key get the same refusal: a key that enumerates is a key that leaks.

Endpoints

All under /api/sign/v1. Sending an envelope through the API is billed exactly like sending it from the app: one envelope, one charge, whatever the door. The API describes itself: every instance serves its OpenAPI 3 document at GET /api/sign/v1/openapi.json, no key needed, and the SDK’s test suite walks every method against it.

The SDK

@rutba/sign-sdk is a dependency-free Node client: every method maps to exactly one endpoint above, so an integration is readable in one sitting and owns no transitive risk.

const { SignClient } = require('@rutba/sign-sdk');

const sign = new SignClient({ baseUrl: 'https://YOUR-INSTANCE', key: process.env.SIGN_API_KEY });

const draft = await sign.createEnvelope({ title: 'Mutual NDA' });
await sign.addDocument(draft.documentId, { name: 'nda.pdf', content: pdfBuffer });
await sign.addParty(draft.documentId, { role: 'signer', name: 'Ada Osei', email: 'ada@example.com' });
await sign.send(draft.documentId);

Webhooks

Set a URL and a signing secret in Rutba Sign’s settings and every envelope event (sign.envelope.*, sign.party.*, sign.document.*) is POSTed to it, at-least-once with retries. Each delivery is signed with an HMAC over `${timestamp}.${body}`; verify it constant-time and timestamp-bounded, or let the SDK do it:

// X-Rutba-Sign-Signature: t=1756800000000,v1=<hex hmac>
const { verifyWebhook } = require('@rutba/sign-sdk');

app.post('/webhooks/rutba-sign', (req, res) => {
  const ok = verifyWebhook({
    body: req.rawBody,                       // the RAW body string
    signature: req.get('x-rutba-sign-signature'),
    secret: process.env.SIGN_WEBHOOK_SECRET, // set beside the URL in Sign's settings
  });
  if (!ok) return res.status(400).end();
  const { event, envelopeId, occurredAt, payload } = JSON.parse(req.rawBody);
  // sign.envelope.sent | sign.envelope.completed | sign.party.signed | ...
  res.status(200).end();                     // non-2xx is retried
});

Verification, without trusting us

GET /verify/{digest} answers valid, tampered or unknown for any sealed record, with no key and no account. The sealed manifest is an Ed25519 JWS over the whole evidence chain, countersigned by Rutba with an RFC 3161 timestamp, so a verifier can check the mathematics without asking anyone’s permission, including ours. POST /verify/receipt does the same for one party’s receipt (their own seal over their act, issued the moment they acted), and GET /verify/document/{sha256} for a file in hand. On the shared app host, app.sign.rutba.io, what you bring is what finds the organization holding the record: the digest, the file’s hash, or the ledger entry a receipt cites. The same file signed in two organizations is not guessed at, and gets the answer a file nobody holds would get.

The platform surface

Everything above is served by the instance that holds the record. One thing is not: the countersignature. When a record seals, and the moment each party acts, the instance presents the digest to Rutba, which signs { iss, digest, received_at } on its own clock. GET strapi.rutba.io/api/sign/public/verify/{digest} answers countersigned (with the JWS, the attested instant, and whether the digest was presented as a manifest or a receipt) or the one constant unknown. The keys are at strapi.rutba.io/api/sign/public/jwks. No key, no account, and the check never touches the instance, so it keeps working whether or not the instance is up. What it attests is existence and time of a digest, and nothing else: not validity, not identity; those are the instance’s verifiers above.

The engine speaks to the platform through two other internal seams an integrator never calls directly: the countersign presentation itself, and the formality desk: a stamp, seal or notarisation a sender asked Rutba to arrange, filed with nothing of the envelope and polled until a person at Rutba records the reference your formality then carries as proof. Both shapes are frozen in the @rutba/contracts pack the engine and the platform each test against.