Primitives

A primitive is one verified action against the user’s wallet credential. Each step in a workflow names a primitive and its params; publishing preserves the customer-selected order for every new session run. In a wallet-backed completion, Alentra builds the request, verifies the signed response, and returns a normalized result.

identify

Disclose attested fields

age_verify

Business-redacted age threshold

light_sign

Sign inline terms

sign

Sign documents

identify

Disclose specific government-attested fields, called blocks. You request only what you need; the user consents to exactly that.

{ "primitive": "identify", "params": { "blocks": ["first_name", "last_name", "dob", "country"] } }

Blocks (mapped to the credential’s data elements):

Block	Meaning
`first_name`	Given name
`last_name`	Family name
`dob`	Date of birth (`YYYY-MM-DD`)
`gender`	Gender
`portrait`	Portrait image
`document_number`	Document/license number
`issue_date`	Issue date (`YYYY-MM-DD`)
`expiry_date`	Expiry date (`YYYY-MM-DD`)
`issuing_authority`	Issuing authority
`country`	Issuing country selected by the verified credential route
`state`	Issuing jurisdiction (e.g. `US-CA`)
`personal_number`	Personal administrative or national identification number, when carried
`address`	Residence address
`resident_state`	Residence state

If blocks is omitted, Alentra requests a sensible default (first_name, last_name, dob, country). A requested block the credential doesn’t carry comes back as JSON null rather than failing the step.

country is the issuing jurisdiction, not residence. A route profile supplies its fixed jurisdiction only when the verified credential omits issuing_country. Google Sandbox uses fictional Utopia data. Claim availability remains profile- specific; a requested block not carried by that profile returns null.

Result (step.completed → data.claims):

{ "claims": { "first_name": "Jane", "last_name": "Doe", "dob": "1990-04-01", "country": "US" } }

age_verify

Prove the holder meets an age threshold without disclosing their birth date. Alentra reads the date from the credential, computes the result, and returns only the boolean verdict plus the requested threshold. The birth date never reaches your age-result webhook.

{ "primitive": "age_verify", "params": { "min_age": 21 } }

min_age is a whole number (1–120; defaults to 18). Result (step.completed):

{ "satisfied": true, "min_age": 21 }

This is “anonymous to you, not to Alentra”: the signer claims and wallet evidence used to compute the result are sealed in the audit record, flagged as redacted, and never exposed on your webhook or session reads.

light_sign

The same device signature, over short inline terms text — no file upload. For consent, acceptance, and disclosure flows.

{ "primitive": "light_sign", "params": { "terms": "I authorize a one-time charge of $49.00." } }

Terms are limited to ~1,000 words (about a 5-minute read).
Alentra canonicalizes the text (normalizes line endings), hashes it, and the wallet signs that hash. The exact terms + hash + signature are kept in the audit, so the signature stays provable.

Terms are shown through the capability URL and retained in cleartext in the immutable audit proof. Do not include secrets or unnecessary personal data.

Result (step.completed; includes the default signer identity fields):

{ "primitive": "light_sign", "claims": { "first_name": "Jane", "last_name": "Doe", "dob": "1990-04-01", "country": "US" }, "signature": "mdoc:3045...", "document_hash": "sha256:1b2c..." }

sign

The holder’s device signs a hash of one or more documents you provide—a what-you-see-is-what-you-sign signature bound to their wallet credential. The workflow definition contains the sign action but no file bytes or document ids. Each run supplies its own files as multipart/form-data.

Alentra computes the SHA-256 of each file and a single manifest digest over all of them (in declared order). The wallet signs the manifest; you never supply a hash.
The user reads the exact bytes Alentra hashed on the hosted page before signing.
Up to 50 files, 50 MB combined. When the step verifies, every referenced original is promoted atomically to immutable evidence alongside the result and audit. Customers cannot delete those completed originals. An upload that never joins a completed sign result remains transient and may be purged after the cleanup window.

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -F 'workflow_id=wf_contract_signature' \
  -F 'metadata={"case_id":"case_4815"}' \
  -F '[email protected]'

Result (step.completed; includes the default signer identity fields):

{ "primitive": "sign", "claims": { "first_name": "Jane", "last_name": "Doe", "dob": "1990-04-01", "country": "US" }, "signature": "mdoc:3045...", "document_hash": "sha256:9f86..." }

Ordering and chaining

Chaining is not a primitive. Add steps in the workflow builder, drag them into the exact order the user should complete them, then publish. API callers pass only that published workflow_id plus run-specific data. Alentra creates one logical step.completed event per step and then a terminal session.* event; delivery retries can arrive late or out of order, so use stage and the delivery id.

Workflow revision 4
identify — first_name, country
age_verify — minimum 18
sign — documents supplied for each run

Gates (pause for a decision)

Existing API-controlled gates in an API-only workflow use a non-final step to pause the session after it completes, so your server can decide whether to continue. Useful when a later step should depend on an earlier result (e.g. only sign if the identity matched your records).

identify → Pause for API decision

On a gated step the session moves to awaiting_decision after step.completed. Resume with POST /v1/sessions/{id}/continue or end it with POST /v1/sessions/{id}/stop. A caller-controlled pause on the final step is rejected. Configured Conditions can follow any primitive, including the final one, and execute automatically in every access mode. They continue to the next proof or result delivery, or stop while keeping verified results.

Reserved: envelope (multi-party)

All primitives today are single-subject. Multi-party signing (Alice → Bob → Carol) is a reserved primitive, not yet available.

Getting Started

Core Concepts

identify

age_verify

light_sign

sign

identify

age_verify

light_sign

sign

Ordering and chaining

Gates (pause for a decision)

Reserved: envelope (multi-party)

identify

age_verify

light_sign

sign

​identify

​age_verify

​light_sign

​sign

​Ordering and chaining

​Gates (pause for a decision)

Reserved: envelope (multi-party)

identify

age_verify

light_sign

sign

Ordering and chaining

Gates (pause for a decision)