BricksID: sign-in and signatures
Bricks Technical Documentation
How an application signs a person in with BricksID, asks them to sign a PDF, reads the outcome and checks the proof.
1. Sign-in is standard OpenID Connect
| Issuer | https://bricks-softwares.com/v2/auth/oidc |
| Discovery | <issuer>/.well-known/openid-configuration |
| Endpoints | <issuer>/authorize, /token, /userinfo, /logout |
| Flow | Authorization code with PKCE (S256), and refresh_token |
| Client authentication | none (PKCE only), or client_secret_basic / client_secret_post for a confidential client |
| Scopes | openid, email, profile, bricks:roles |
The person always signs in on a BricksID screen, never in your application: with their password, or with a link sent to their address, which works once and for 15 minutes. Someone who turned on two-step sign-in is also asked for a code. Lifetimes: a code lasts 10 minutes, an access token one hour, a refresh token 30 days and it rotates on each use.
The callback. redirect_uri must match a registered address exactly. If a check fails at /authorize, the browser goes to a BricksID error page and never to the unverified address. A person your application restricts by role gets access_denied.
Who signed in. Call /userinfo with the access token. It returns sub, email, email_verified, name, and roles when bricks:roles was granted. email_verified is true when the person has proven they receive mail at that address; the id_token carries it too. When the person signed in on behalf of someone they represent, it also returns bricks_mandate.
An application published on Bricks
Nothing to configure. Each publish registers the application and its addresses, including custom domains, with the callback /auth/callback. In the application:
import { connectWithBricksID } from '$lib/bricks';
await connectWithBricksID(); // a small window over the app
await connectWithBricksID({ mode: 'redirect' }); // a full-page redirect
A system outside Bricks
Bricks registers the client on request, with your callback addresses (one per environment if you like); there is no self-service registration yet. Signing in through such a client identifies the person and grants nothing in any organisation.
A system with its own server can be registered as a confidential client: Bricks gives you a secret once, and /token (code exchange and refresh) refuses your client without it, in a Basic header or as client_secret in the body. PKCE is still required.
The id_token is signed with the algorithm discovery states in id_token_signing_alg_values_supported, with the public key at /jwks for RS256. When discovery states HS256, the id_token cannot be verified outside Bricks: read the person from /userinfo with the access token.
2. Asking a person to sign a PDF
A signature made this way is a simple electronic signature under eIDAS: admissible as evidence, its weight argued from the sealed proof. It is neither advanced nor qualified, and must not be presented as such.
Only the person signed in can be asked. No application can address someone else or sign for anyone: the person reads and signs on a BricksID page, in their own session.
The person keeps the image of their handwritten signature in BricksID, drawn or from a scan, and it is placed on every document they sign. Your application never receives that image: it receives the signed document, with the image on it. Someone who has not set it yet does so on the signing page.
From the application, with the access token of the person signed in:
POST /v2/me/signature-requests
Authorization: Bearer <access token>
Content-Type: application/json
{
"title": "Membership agreement 2027",
"document_name": "agreement-2027.pdf",
"document_base64": "JVBERi0xLjcK…",
"expires_in_days": 30,
"signature_box": { "page": 2, "x": 330, "y": 60, "width": 200, "height": 70 }
}
| Field | |
|---|---|
title |
Required, 1 to 200 characters. Shown to the person. |
document_base64 |
Required. A PDF, at most 10 MB. |
document_name |
Optional. Default document.pdf. |
expires_in_days |
Optional, 1 to 90. Default 30. |
signature_box |
Optional. Where the signature is placed, like a signature field: page from 1, then x, y, width, height in PDF points from the page's bottom-left corner (an A4 page is 595 × 842). It must lie within that page. Without it, the signature goes on a page added at the end of the document. |
The PDF must be one the signature can be placed on: an encrypted or damaged PDF is refused.
The answer is 201 with signature_id, sign_url and expires_at. Send the person to sign_url, by redirect or in a window.
From a workflow, after an action-authenticate step: the node action-request-signature (titleExpression, documentExpression, documentNameExpression, expiresInDays, signatureBox) returns the same three values. documentExpression is typically the content output of action-pdf-fill.
3. Knowing the outcome
Opened in a window over your application, the signing page posts this message to your application's registered origin, then closes:
{ source: 'bricksid', type: 'signature-signed', signature_id: '…' }
// or type: 'signature-declined'
Check event.origin, then read the signature to confirm it: a message is a hint, the API is the answer.
Reading the signature: GET /v2/me/signatures/:id with the person's token, or the workflow node action-read-signature. status is open, signed, declined or expired; evidence is empty until the person signs. GET /v2/me/signatures lists the signatures your organisation asked of that person, and GET /v2/me/signatures/:id/document returns the PDF: once signed, the signed document, with the signature placed on it; ?version=original returns the document as you sent it. signed_document gives the signed document's size and SHA-256.
The proof travels beside the PDF, not inside it.
4. Checking the proof
Signing records a sealed evidence object:
{
"evidence": {
"kind": "bricks.signature.v1",
"issuer": "bricks-softwares.com",
"key_id": "bricksid-seal-prod",
"signature_id": "6f7c1e52-…",
"title": "Membership agreement 2027",
"document": { "name": "agreement-2027.pdf", "media_type": "application/pdf", "size": 48213, "sha256": "9f2c…" },
"signed_document": { "media_type": "application/pdf", "size": 51870, "sha256": "4b1e…" },
"specimen": { "sha256": "8702…" },
"signer": { "id": "a7000001-…", "name": "Ada Example", "email": "ada@example.org", "email_proven": true, "second_factor": false },
"organisation": { "id": "b7000001-…", "name": "Example Club" },
"app": "03ee6b6c-…",
"requested_at": "2026-11-06T10:00:00.000Z",
"signed_at": "2026-11-06T10:05:12.000Z"
},
"seal": "…",
"key_id": "bricksid-seal-prod"
}
documentis the PDF you sent;signed_documentthe PDF with the signature placed on it;specimenthe fingerprint of the signature image placed.email_proven: the person proved the address by following a link sent to it.second_factor: the person protects their sign-in with a second factor, so the session that signed passed it.- The seal is Ed25519 over the canonical JSON of
evidence: keys sorted at every depth, no whitespace.
Anyone holding the proof can check it, without an account:
POST /v2/signatures/verify
Content-Type: application/json
{ "evidence": { … }, "seal": "…", "document_base64": "JVBERi0xLjcK…" }
The answer is { "valid": true, "document": "original" | "signed" } — which of the two documents the bytes given are — or { "valid": false, "reason": … } with malformed, unknown_key_id, invalid_seal, outside_key_window, or document_mismatch when the bytes given are neither. document_base64 is optional. GET /v2/signatures/public-keys lists every key ever used, retired ones included.
5. Errors
Errors carry a code:
| Status | Code | Meaning |
|---|---|---|
| 400 | signature.title, signature.document_name |
Missing or too long |
| 400 | signature.document_empty, signature.document_too_large, signature.document_not_pdf |
The file is refused; nothing is stored |
| 400 | signature.expiry |
Not 1 to 90 days |
| 400 | signature.document_unreadable |
The PDF is encrypted or damaged: the signature could not be placed on it |
| 400 | signature.box_outside |
signature_box names a page the document does not have, or lies outside it |
| 403 | signature.from_app_only |
Asked from outside an application belonging to an organisation |
| 403 | signature.own_session_only |
Signing was attempted with an application's token |
| 403 | signature.no_key |
An API key cannot read or sign |
| 403 | signature.under_mandate |
A signature is always the signer's own: nobody signs as someone they represent |
| 404 | signature.not_found |
Does not exist, or was not addressed to this person or organisation |
| 409 | signature.not_open |
Already signed or declined, or expired |
| 409 | signature.no_specimen |
The person has not set their signature image yet; the signing page asks them to |
| 503 | signature.sealing_unavailable |
This environment cannot seal, so nothing can be signed |
6. Where people see it
In their BricksID, the person sets their signature image under Identity and finds every request and every signature under Contracts & mandates (/account/commitments, full list at /account/signatures), with the signed document and a proof file they can keep, whatever happens to the organisation that asked. It stays theirs until they delete their account.
The organisation receives the proof, including the signer's name and email address. Its privacy information should say so.
Current limits
- Simple electronic signatures only.
- One signer and one signature box per request. Nobody can yet sign on behalf of a person they represent or of an organisation.
- No webhook when a person signs. After a full-page redirect, the person is not sent back to your application: read the signature when they return.
- Signature requests come from applications published on Bricks and from workflows, not yet from clients outside Bricks.
- BricksID does not verify a person's legal identity: it knows their account, whether their email address is proven, and whether a second factor protects it.
- An organisation can only ask the person signed in; it cannot send a request to someone by email.