---
title: Unlock forms overview
description: How unlock forms hold an imported recipient's certificate until they respond
group: Unlock Forms
---

# Unlock forms overview

# Unlock forms overview

An **unlock form** is completed by someone you have already imported. Their
certificate issue exists and is `pending`; submitting the form releases it. This
is different from a **certificate request**, which is an application from a
person who may not be a recipient at all and which may create a new issue.

An unlock submission can never create a recipient or a certificate issue.

## Flow

1. Turn the unlock form on for a certificate.
2. Import recipients. Each pending issue gets a private **unlock invitation**.
3. When the certificate is active, every eligible recipient is emailed their own
   unlock link. Importing into a draft defers this until you publish.
4. The recipient opens the link, with no login or one-time code, and submits.
5. Under `release_on_submission` the certificate is released immediately. Under
   `manual_review` it waits in your Unlock Responses inbox.

## The unlock link

The token in an unlock link is a bearer capability scoped to exactly **one**
certificate issue and one unlock form. Possession of it permits only:

- viewing the issuer, certificate, known recipient name, and published form;
- uploading files for that invitation;
- submitting or resubmitting that invitation's response;
- opening the released certificate for the same issue.

It never lists other recipients, changes the recipient's email, creates an
issue, or performs organizer actions.

- Tokens carry at least 256 bits of randomness and are **never** stored: only
  `SHA-256(token)` is persisted, so a reminder necessarily issues a fresh link
  and atomically retires the previous one.
- A `GET` does **not** consume the link. Mail scanners and link previews open it
  before the human does, so opening is recorded but the invitation stays usable.
- Invalid, revoked, expired, and unauthorized tokens all answer with the same
  `404 unlock_link_invalid`, so probing reveals nothing.

## Pending reasons

While an issue is `pending`, `pending_reason` says what it is waiting on:

| Value             | Meaning                                          |
| ----------------- | ------------------------------------------------ |
| `manual_issue`    | Waiting for an organizer to send it              |
| `unlock_response` | Waiting for the recipient to submit the form     |
| `unlock_review`   | Submitted, waiting for the organizer's review    |

`pending_reason` is `null` once the issue is `active`. Response status and issue
status describe different facts and are never conflated.

## Idempotency

Invitation fan-out, submission, and review are all safe to retry:

- Sending invitations reports recipients who already hold a live link instead of
  mailing them again.
- A repeated submission after a network timeout returns the current state; it
  never releases twice, spends a second credit, or creates a second issue.
- Accepting an already-released response is a no-op.

## Error codes

`unlock_not_enabled`, `unlock_link_invalid`, `unlock_already_released`,
`unlock_response_required`,
`certificate_issue_not_pending`, `invalid_release_policy`.