TrustBridge quick reference

The essentials of Lacuna TrustBridge on one page, with links to the full articles.

What it is for

Lacuna TrustBridge lets your server-side application sign PDF documents with a person's ICP-Brasil certificate through a REST API, while the private key stays where it lives: on a smart card, a USB token or in the Windows store of the holder's workstation, or, when the deployment opts in, in a vault on the TrustBridge Server. Your application sends the holder's CPF and PIN once to open a Signing Session, then signs under it; it never learns which custody answered. TrustBridge is self-hosted: you run the Server (a Linux container) and install the Workstation package on each holder's Windows machine. Lacuna Signer does the document work (hash, PDF assembly, signed-document download); TrustBridge signs hashes and stores no documents.

Choose instead	When it fits better
CloudHub	The certificates are cloud certificates held at an ICP-Brasil provider (a PSC), not on tokens or machines you manage.
Rest PKI Core	The person signs while using your web application, in their browser, and you want a hosted signing page.
Web PKI	Your own web page must reach the certificates on the user's computer from JavaScript while they are at it.
Signer	You need a document workflow: participants, notifications, approvals, a signing page for each person.

Install

There is no client library: the API is plain HTTP and JSON (or multipart), so any HTTP client works. What you deploy:

Component	Ships as	Current version	Guide
Server	Container image trustbridge-server, on Docker (Linux) or Azure App Service, with SQL Server	1.13.0	Server installation, Azure App Service
Workstation Service and Tray App	Signed MSI TrustBridge-Workstation-<version>-x64.msi, one per holder's Windows machine	1.5.0	Workstation installation

• Every Server needs a Lacuna PKI SDK licence (Certificates:Validation:License, PKI_LICENSE in the Docker .env), and hands it to every admitted workstation; the MSI takes no licence.
• Workstation 1.5.0 needs Server 1.13.0, and the two are upgraded together. A machine on an older release does not take part in creating sessions on Server 1.13.0. See Changelog.
• A new machine waits in the admission queue until an Administrator admits it on the admin console.

Configuration and authentication

The base address is your own Server's (for example https://trustbridge.example.com), and every operation is under /v1; a bare route answers 404 ENDPOINT_NOT_FOUND. Every call needs an API key in the X-API-Key header.

• Get a key on the admin console's Client Applications screen (/admin/applications): register your application, then Issue key. The value is shown once and only its hash is stored.
• A bad key is always 401 UNAUTHORIZED, whether missing, unknown, revoked, expired or its application disabled.
• Treat sessionId and signatureId as bearer tokens: any accepted key can use a session or fetch a document whose id it holds. Keep them out of logs.
• Quote X-Correlation-Id (on every response, errors included) when reporting a problem.

Core operations

Create a session, sign under it, fetch the signed PDF (which is also where you read the outcome), and end the session. The REST API page documents every operation; a running Server serves the OpenAPI document at /openapi/v1.json and a browsable reference at /scalar, both without a credential.

Create a Signing Session

POST /v1/sessions with the holder's cpf (eleven digits, check digits verified) and pin; optionally sessionDuration in seconds (above the maximum is clamped) and email, a fallback address for a certificate that names none.

curl -s https://trustbridge.example.com/v1/sessions \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "cpf": "12345678909", "pin": "1234", "sessionDuration": 3600 }'

{ "sessionId": "8f3c…", "cpf": "12345678909", "expiresIn": 3600, "expiresAt": "2026-09-21T15:04:05Z" }

The Server tries the Vault Certificates for that CPF first, then asks the workstations holding a certificate for it to prove they hold the PIN; the PIN itself never leaves the Server. When no workstation has the PIN cached, the holder is prompted at their Tray App and the request stays open until they answer or the prompt times out (60 s by default): set a generous client timeout. One session is active per CPF; creating another replaces it.

Sign for a Company

Add cnpj (fourteen characters, the alphanumeric CNPJ accepted) to sign with a Company's e-CNPJ; cpf is still the person who holds it. With a cnpj only that Company's e-CNPJ can bind the session, and without one an e-CNPJ never can. The answers carry cnpj only when one applies. Needs Server 1.13.0.

{ "cpf": "12345678909", "cnpj": "12ABC34501DE35", "pin": "1234" }

Sign a document

POST /v1/signatures with the sessionId and a PDF, as JSON (document base64-encoded, optional fileName) or as multipart. It signs inside the request and answers 202 with the signatureId and the fileName it signed under.

curl -s https://trustbridge.example.com/v1/signatures \
  -H "X-API-Key: $API_KEY" \
  -F "sessionId=8f3c…" -F "document=@contract.pdf"

{ "signatureId": "a1b2…", "fileName": "contract.pdf", "status": "PROCESSING", "acceptedAt": "2026-09-21T14:10:00Z" }

A 202 is not "it worked": read the outcome at the fetch. Only PDFs are signed, up to 10 MB by default. For several documents, POST /v1/signatures/batch takes up to 50 file parts (by default) in one multipart call and answers one result per document, in order; read each result rather than the status code. A batch is one call for the throttle and for the Signature Allowance.

Fetch the signed document

GET /v1/signatures/{signatureId}/document. Poll on 409 DOCUMENT_NOT_READY; stop on 200 (the signed PDF) or 422 DOCUMENT_UNAVAILABLE (refused, cancelled or expired). There is no webhook. How long a document stays fetchable is Lacuna Signer's retention, since the Server stores nothing.

curl -s https://trustbridge.example.com/v1/signatures/a1b2…/document \
  -H "X-API-Key: $API_KEY" -o signed.pdf -w '%{http_code}\n'

Check, describe and end a session

• GET /v1/sessions/status?sessionId=… answers active and the time left; it never extends the session. Signing does extend it.
• GET /v1/certificates/info?sessionId=… describes the bound certificate; check that status is ACTIVE before signing.
• POST /v1/sessions/deactivate with { "sessionId": "…" } ends it at once; with nothing active it answers 401 SESSION_EXPIRED.

Errors

Every error is { "error": { "code", "message", "details" } }. Branch on code, never on message, and treat an unknown code as an unexpected failure. See The error envelope.

• SESSION_EXPIRED (401) on any call: the session expired, was deactivated, replaced or used up its Signature Allowance. Create a new one.
• INVALID_PIN (401): every candidate certificate was tried and none matched. TOO_MANY_PIN_ATTEMPTS (429) is the per-CPF lockout: retrying makes it worse.
• PIN_NOT_AVAILABLE (422): no comparison could be made (prompt timed out or declined, vault certificate not opened, too many recent failed attempts); details says which. WORKSTATION_OFFLINE (422): the holder's machines are offline or on a Workstation release older than 1.5.0.
• CERT_NOT_FOUND (404) / CERT_NOT_ACTIVE (422): no certificate for the CPF, or none with an ACTIVE verdict.
• SIGNER_REJECTED (422) vs SIGNER_ERROR (502): the signature service refused the request (don't resend it unchanged) vs could not be reached (nothing was signed; resend later).
• SERVER_BUSY (429): the Server is at capacity; retry with your own backoff and jitter (no Retry-After).

Troubleshooting maps each code to what an operator checks.

Test certificates and credentials

• TrustBridge signs only with certificates whose chain it trusts. To sign with test certificates from a private CA, an Administrator adds that CA on the Trusted CAs screen, which reaches every admitted workstation without a restart.
• The Lacuna Test PKI certificates page has no TrustBridge section.

TODO(docs): whether Lacuna offers a hosted TrustBridge test Server or sandbox, and whether the Lacuna Test PKI root can be added as a Trusted CA for testing.

Try it

• On a running Server, open /scalar to browse the contract and try calls with an API key.
• Lacuna Software can provide a Postman collection of the contract with an environment carrying a sample PDF: create a session, sign, fetch. See Trying the contract by hand.

TODO(docs): no TrustBridge demo or sample project is published.