Agreely
FR EN

Consent requests

A consent request is a signed offer, made to one customer, for a set of catalog cells. It is delivered as a secure deep link (and sent by email) that the person concerned opens to review the offer and consent with a passkey in the Citizen portal.

What a request carries

  • The items: the catalog cells the offer targets.
  • The company's customer id (customer_id): your own id for this customer, never a citizen's decentralized identifier.
  • The recipient email: where the link is sent.
  • The valid-until date (valid-until): past it, the offer expires.
  • The recipient language: French or English, so the offer is presented in the person's language.
  • The minor fields (article 4.1): an "is a minor" flag, parental consent, and by whom it is given.

Issuing conditions

Issuing a request requires a verified domain and an active signing key. The reason is direct: an offer is signed on behalf of the company, so that it is independently verifiable. Without a did:web identity minted by domain verification and without an active signing key, there is nothing to sign the offer with, and issuing is blocked.

Domain verification comes first

If issuing is blocked, the most common cause is an unverified domain or the absence of an active signing key. See Domain and branding to verify the domain and manage keys.

The lifecycle

A request moves through a precise status set:

  • pending (pending): issued, awaiting the person's response.
  • approved (approved): the person concerned consented.
  • refused (refused): the person concerned declined.
  • expired (expired): the valid-until date passed with no response.
  • revoked_before_action (revoked_before_action): the company cancelled the offer before the person acted.

An approved request produces the consent in effect for the targeted cells; that status is what a verification then reads, as described in Core concepts.

Issuing via the API

The same request can be issued via the /v1 API: POST /v1/consent-requests, under the issue scope. Issuing accepts an idempotency key, so that a replayed send does not create a duplicate offer. This is the preferred path for issuing in bulk or embedding issuance in your own flows.

See the API reference for the full contract, along with the TypeScript SDK, the PHP SDK, and the CLI to issue from your code or your terminal.

Not every person concerned has a passkey. For the no-passkey case (for example an elderly person who signs on paper), there is a separate path: offline, company-attested consent. The person concerned holds a hand-signed PDF, and the company records that consent under the attest scope.

A separate path, not a shortcut

Attested consent carries no passkey assertion from the person concerned: it is the company attesting that it collected a paper consent. It is a legitimate path for no-passkey cases, distinct from the signed offer the person approves themselves. It requires the attest scope and a retained supporting document.

See the Citizen portal and the offline consent guide for the full path on the person's side.

Next