Organization seal
Machine-to-machine sealing of documents with an organization key, using signed JWS requests and no human signer.
An organization seal is a signature made under authority that the administrator has assigned to an organization. There is no signer, browser, identity provider or consent step, but the requesting system must still authenticate with a registered key.
The mode is selected with service set to organization-seal-v1 and runs as a separate server instance. Organization seals use machine authorization and the configured organization credential. Use the DSS or CSC service for human document signing.
Request
Section titled “Request”Send POST /api/seal/v1 over HTTPS with Content-Type: application/jose, no query string and no content encoding. The body is one compact JWS of at most 131,072 bytes.
The protected header contains exactly:
| Member | Value |
|---|---|
alg |
RS256, the only accepted algorithm. |
kid |
The identifier of the requester's registered key. |
typ |
idombud-seal-request+jws |
The administrator pins each requester's RSA public key. Keys, URLs, certificates or algorithms supplied in a request cannot establish trust, and unknown or duplicate members are rejected.
The payload is at most 65,536 decoded bytes and contains exactly these members:
| Field | Meaning |
|---|---|
version |
The integer 1. |
request_id |
20–96 characters matching [A-Za-z0-9][A-Za-z0-9._:-]*, unique per requester. |
audience |
The exact configured audience URI. |
organization |
A registered organization identifier. |
profile |
A registered organization profile identifier. |
issued_at |
UTC RFC 3339 instant. |
expires_at |
Exclusive UTC expiry, later than issued_at and at most 60 seconds after it. |
inputs |
An ordered array of 1–8 inputs, each with an id and signed_attributes. |
signed_attributes is standard Base64 of DER CMS signed attributes, at most 8,192 decoded bytes, in the detached CMS SHA-256 with RSA form. The original documents stay with the requesting system. The request cannot name a credential, key alias, native module or person.
The key identified by kid determines the requester, and a configured grant must allow the exact organization and profile. The server selects the signing credential from the profile.
Response
Section titled “Response”On success the server returns 200 with application/json:
| Field | Meaning |
|---|---|
version, request_id |
As in the request. |
transaction_id |
seal- followed by SHA-256 of the requester, a zero byte and the request ID. |
organization, profile |
The registered values used. |
algorithm |
RSA_PKCS1_SHA256 |
completed_at |
Server completion time. This is not a trusted time stamp. |
certificate_chain |
The configured public chain as Base64 DER. |
leaf_sha256 |
SHA-256 of the leaf certificate. |
results |
The ordered {id, signature} entries, Base64. |
The requesting system must verify each signature over its exact DER attributes, check the messageDigest against the retained original, and check the certificate against the organization certificate it expects.
Errors
Section titled “Errors”Errors are returned as { "error": "..." } without submitted values or internal details.
| Status | error |
Action |
|---|---|---|
| 400 | invalid_request |
Correct the syntax or limits. Nothing was signed. |
| 401 | unauthenticated |
Check the registered key and the JWS. |
| 403 | not_authorized |
Check the audience and the organization and profile grant. |
| 408 | expired_request |
Nothing was signed for this attempt. Reconcile any earlier attempt before using new authority. |
| 409 | duplicate_request |
The request ID is already consumed. Reconcile and do not create another ID silently. |
| 413 | request_too_large |
Reduce the request. |
| 415 | unsupported_media_type |
Use application/jose. |
| 429 | capacity_exceeded |
Retry the same request ID within its lifetime. |
| 503 | unavailable |
The server was not ready. Nothing was consumed. |
| 503 | outcome_unknown |
Signing may have happened. Reconcile before doing anything else. |
A request ID is consumed durably before the private-key operation. A consumed operation is never resumed or reset, and there is no way to fetch an earlier result. After a timeout, a lost connection or outcome_unknown, reconcile in your own business process and never submit a new ID automatically.
Configuration
Section titled “Configuration”The configuration root contains schema_version, service, listener, database, audience, requesters, profiles and optionally resources and event_log. Human SAML, DSS and identity provider sections are rejected in this mode. The listener and database sections are described under Configuration.
| Section | Description |
|---|---|
audience |
The absolute URI that requests must name. Each independent authorization domain needs its own audience. Instances that share an audience and requesters must share the database. |
requesters |
Each entry has requester, a unique kid, public_key_file (RSA 2048–4096 bits as DER SubjectPublicKeyInfo) and grants, each with an organization and a profile. |
profiles |
Each entry has organization, profile, certificate_sha256 (the lowercase hex SHA-256 of the leaf certificate) and a signing section for PKCS#12 or PKCS#11. |
resources |
Optional untrusted_work (1–64, default 8), trusted_work (1–32, default 4) and trusted_per_requester (1–trusted_work, default 2). A full budget returns 429 without consuming an ID. |
The signing key of each profile must be distinct from every TLS and requester key, judged by the actual public key. The leaf certificate must not carry an Extended Key Usage extension. Registrations are read at startup, and a changed file makes readiness fail instead of reloading.
The launcher supports config-check, database-check, schema-prepare, start, health-check and diagnostics. Startup prints SIGNING_READY service=organization-seal-v1. The diagnostics command reads public registrations and aggregate audit counts without signing and without starting a listener.
Keep consumed request IDs when you back up or migrate the database. A restored, stale database cannot show that an ID was never consumed.