Milestone: M7 — Reclaim Protocol | SOW Reference: FR4 | Requirement Clarity: ✅ Clear (recommendation already made — Flow A) | Dev Status: ❌ Not started Moved from docs/requirements/tasks/POC/23-reclaim-candidate-flow-design.md — unmodified below.

M7-05 Reclaim Protocol — Candidate Flow Design¶

Audience: NeuralRays engineering (internal) Purpose: Answer the "do candidates need a login?" question and pick the flow we build first Status: Draft — pending client answers to M7-01 scope confirmation Section 5

Candidates do NOT need to log into our platform.

The only login involved in Reclaim Protocol is at the target site — e.g. HMRC's Government Gateway. That login happens in the candidate's own browser, directly with HMRC. Our platform never sees the candidate's HMRC password, and Reclaim's witness network doesn't see it either.

What we need to decide is simply: where does the candidate land in order to trigger the verification? Three options below.

2. Three Candidate-Entry Flows¶

Flow A — Email-token, no candidate account on our platform¶

Mirrors the claim-page pattern already shipped. Agency triggers a request → candidate gets an email → clicks a signed tokenized link → lands on a public verification page → Reclaim widget runs → proof posts back.

Agency admin ──"Request HMRC verification for Jane"──► our backend
                                                           │
our backend ──generates signed token──► SES email ────► Jane's inbox
                                                           │
Jane clicks link ─► /verify/{token} page (public, no login)
                    │
                    Reclaim SDK loads → Jane logs into HMRC
                    → proof posted back to /external-claims/submit
                    ↓
Agency dashboard shows "Verified directly from HMRC: ..."

Pros - Zero friction for the candidate - Reuses the claim_token machinery already in production - No new Auth0 role, no registration UI, no password reset flow - Matches how staffing agencies operate in practice (one verification per hire)

Cons - Token link has to remain valid long enough for the candidate to complete HMRC login (~24h) - No "my past verifications" history for the candidate — each agency triggers a fresh proof

Flow B — Full candidate account on our platform¶

Candidate registers, logs in, sees a dashboard of providers (HMRC, bank, LinkedIn). They verify once and reuse proofs across multiple agencies.

Pros - Reusable proofs — candidate does HMRC once, shares with many agencies - Proper audit trail per candidate - Foundation for a candidate-facing "verifiable résumé"

Cons - Full candidate auth flow: registration, password recovery, MFA - UI to manage proofs, pick which to share, revoke stale ones - Arguably duplicates the role of a digital wallet (Velocity holder wallets already do exactly this)

Flow C — Redirect to Reclaim's hosted UI¶

We link out to a Reclaim-hosted portal; proofs arrive back via webhook.

Pros - Least code we write

Cons - Candidate leaves our brand entirely - Less control over UX, consent copy, error messaging - Weaker position when the client wants visual customization for their members

3. Recommendation — Flow A for the REC member trial¶

For the upcoming real-trial deployment with one REC member, Flow A is the right starting point.

Why 1. The token + email-link infrastructure is already live for the Velocity claim flow. Reclaim reuses the same pattern end to end — a fresh controller on the same signed-token primitive. New code is additive, not structural. 2. A new candidate auth surface (Flow B) would be the single biggest item in the rescope. Skipping it keeps the trial focused on the thing the client actually asked for: pulling data from HMRC and similar sources. 3. Every staffing hire cycle is a fresh context anyway. A candidate applying to Acme this month and to Beta Staffing next month typically doesn't mind re-verifying — and it's a stronger privacy story (no long-lived session on our servers). 4. If reusability becomes a client requirement after the trial, we can upgrade Flow A to Flow B by adding magic-link history access (email a login link to {email}, list previous proofs) — still no password, still a small UX addition. Drop 2 work.

What we're giving up by choosing A: the candidate-owned wallet experience. That's legitimately valuable, but it's also the Velocity wallet's job. We don't need to reinvent it inside our platform for a trial.

4. Flow A — Concrete UX¶

Agency admin dashboard On the existing candidate/employee row, a new action button: Request external verification. Opens a picker for HMRC / Open Banking / LinkedIn / etc. Admin chooses provider + which fields they need confirmed → submits.
Email to candidate (templated, SES-delivered)

"Acme Staffing would like to verify your employment history directly with HMRC. This takes about 90 seconds and does not share your password with anyone. [ Verify now → ]" Link carries a signed, single-use token (same primitive as claim_token).
Public verification page /verify/{token}
Consent copy: what's being shared, with whom, how long it's retained
"Continue to HMRC" button launches the Reclaim SDK widget
Candidate authenticates with HMRC on HMRC's own pages, inside the widget
Picks which fields to share (Reclaim's own UI)
SDK produces the proof, posts to POST /external-claims/submit
Confirmation page

"Verified. The proof has been sent to Acme Staffing. You can close this window."
Agency dashboard New "External Verifications" tile under the candidate's profile showing:
Provider (HMRC)
Extracted fields (employer name, dates, income bracket — whatever the provider returns)
Timestamp
Raw proof available for download / re-verification

5. Privacy consequence worth naming explicitly¶

Flow A means the candidate doesn't need to remember us for their next hiring cycle. Each agency triggers a fresh verification, and each proof stands alone. That's a feature, not a bug — it keeps us off the critical path of the candidate's identity management and aligns with data-minimization principles under UK GDPR.

If the client wants a candidate-owned history layer later, we add it; we don't pre-build it.

6. Open items this design does not yet answer¶

These are resolved by the seven questions in Task 22:

Which data sources beyond HMRC are in scope → changes the number of provider recipes we need to configure
Whether Reclaim proofs should also be minted as Velocity VCs → determines if the proof lands in a new table only, or also flows through CihApiService.createCredential
Candidate- vs agency-initiated → Flow A covers agency-initiated; candidate-initiated would add a small self-service entry point

Once Task 22 gets client answers, this document can graduate from "draft" to "approved for implementation".