Skip to main content
A session is one non-repeatable run of a published workflow. It snapshots that workflow’s ordered primitive steps, revision, and definition hash. Developers can create API-only runs server-to-server; authorized members can create and optionally email one-time links from the workflow. Each explicit start from a reusable link creates a separate session.

​
Lifecycle

1

created

POST /v1/sessions with a published workflow_id returns the session and its hosted url. Nothing is charged.
2

in_progress

The user opens the hosted page, explicitly starts on that browser, and begins; each step’s wallet response is verified and emits step.completed.
3

awaiting_decision (optional)

If a step is an API-controlled gate, the session pauses here until you continue or stop it. Configured workflow conditions evaluate automatically after verification and do not enter this state.
4

completed / stopped / failed / expired

A terminal state. The matching session.* webhook fires. Original files that participated in a completed sign step remain immutable evidence; only explicit transient uploads from uncompleted sign steps become cleanup-eligible.

​
The hosted page & capability URLs

The session url (https://alentra.app/s/{id}) is a capability URL — holding the link is what lets a user open the session. Treat it like a secret: deliver it over a channel only the intended user controls (your authenticated app, their phone).
Explicit-start binding. Loading or previewing the page is read-only. The first browser whose user presses Start secure session is cryptographically bound; only that browser can submit a wallet response. A second device may load the neutral page but is refused when it tries to start. This also prevents email scanners from consuming an invitation.
One-time dashboard invitations expire exactly 24 hours after creation. Emailing or resending the opaque link never extends that deadline or identify the signer. Once the user starts, each wallet step also has its shorter 3/10/30-minute security window. Terminal signer access to completed materials remains available for 48 hours in the original bound browser, unless the signer closes online access earlier. After any completed step, the bound browser can Download receipt (PDF) without entering an email. This includes the completed results, audit references, and a structured JSON attachment for technical verification. Incomplete sessions produce a clearly labelled partial receipt; sandbox simulations stay labelled as examples. The PDF is a readable record, not a new signature on a document. Signed originals can be downloaded separately. Saved files do not expire when online access ends. Email me a receipt is optional. Verify the destination with a six-digit code, then Alentra emails a PDF attachment containing the completed results and audit references. The code lasts up to ten minutes; the page shows its countdown and a resend option after one minute. Sending is limited to five codes per hour per session. Keep the attachment private. It remains available after online access ends. The original browser’s session page is the signer’s place to download receipts and signed originals. After the session ends, Close online access permanently disables those downloads and further receipt emails, without changing the session outcome or retained evidence. A warning appears when no PDF download was recorded in that browser; it cannot confirm that a file was saved. Copies already saved or emailed remain available. A delivery authorized before closure may already be in flight. Receipt emails contain a PDF attachment. The separate receipt page and public receipt-link downloads have been removed, including for previously emailed links. Use the original browser’s session page for online access.

​
Reading a session

GET /v1/sessions/{id}, authenticated with your API key, returns status plus results already produced: requested identify claims, age_verify’s boolean and threshold, and signing hashes/signatures. The unauthenticated hosted status projection contains no results. The bound signer can explicitly read their completed prefix through GET /v1/sessions/{id}/receipt; this read never starts or advances the session and requires the existing binding cookie. Webhooks remain the primary push channel; use GET to reconcile a missed event, not as a polling loop.

​
Run-specific options

The workflow owns the ordered steps. POST /v1/sessions accepts the published workflow_id plus these optional values for one run: Plus an optional Idempotency-Key header so a retried create returns the original session instead of a duplicate. See Create a session for the full reference. Treat metadata as retained operational data, not a secret store. There is no recipient_email API option. Dashboard invitation email is delivery of an opaque one-time link only. At completion, the signer independently chooses whether to send their result to a verified email address.

​
Expiry

Sessions have an overall TTL (1 hour by default, or a 60-second–24-hour expires_in override), and each step has its own shorter window once started. Expiry is enforced on the next state access, persisted, and enqueued as one logical session.expired event (transport retries remain at-least-once).

​
Result retention

Completed results and their audit records are legally significant service records. They are immutable and are not customer-deletable. For a completed sign, this also includes the exact original document bytes Alentra hashed and presented to the signer. Stopping or deleting a customer account does not erase them. Any account/data request is reviewed for disposable data and legal holds; cleanup jobs may remove only data explicitly classified as transient, such as an upload that never joined a completed sign result.

Next: Wallets & coverage

Which wallets and countries can complete a session today.