# 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:

```ts
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:

```http
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:

```js
{ 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:

```json
{
  "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"
}
```

- `document` is the PDF you sent; `signed_document` the PDF with the signature placed on it; `specimen` the 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:

```http
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.
