Every team has ad-hoc one-time token logic hiding somewhere. Here's what ExactOnce replaces — and why the replacement is worth it.
Most magic link implementations store a token in the database, check it on request, then mark it used. The window between "check" and "mark" is a race condition. Two tabs clicking the same link can both succeed.
ExactOnce's conditional write closes that window at the storage layer. One request wins. The second gets a 409. No matter how fast they arrive.
// 1. User requests sign-in POST /v1/actions { "payload": { "type": "magic_link", "user_id": "usr_abc123" }, "expires_at": "2026-02-19T00:15:00Z" } // → actionId: "act_7f3k9mZn4pQ" // 2. Email: "Click to sign in → /auth?a=act_7f3k..." // 3. User clicks link POST /v1/actions/act_7f3k9mZn4pQ/consume // → 200, payload.user_id → sign them in // 4. Second click (different tab, replay attack) POST /v1/actions/act_7f3k9mZn4pQ/consume // → 409 already_used. Access denied.
A reset link that can be clicked twice is a vulnerability. If an attacker intercepts the email (or the user forwards it accidentally), a reusable link gives them a path in — even after the user has already reset their password.
ExactOnce makes reset links single-use by design. The first consume sets the new password. The second attempt returns 409. The link is dead.
// Create reset action (server-side) { "payload": { "type": "password_reset", "user_id": "usr_abc123", "email": "alex@company.com" }, "expires_at": "2026-02-19T01:00:00Z" } // User submits new password → consume action POST /v1/actions/act_.../consume // On 200: update password for payload.user_id // On 410: show "link expired, request a new one" // On 409: show "link already used" // Attacker replays the intercepted link: // → 409. Game over.
Invite links forwarded to the wrong person, or clicked twice in different browsers, can create duplicate memberships or grant unintended access. Expiring invites are usually enough — but expiry alone doesn't stop forwarded links.
With ExactOnce, one click joins the team. A forwarded link gets a 409. Combine with PIN protection for high-value invites — only the intended recipient can accept. After three wrong PINs, the invite is invalidated.
// Create invite (7-day window) { "payload": { "type": "team_invite", "team_id": "team_xyz", "role": "member", "invited_by": "usr_admin" }, "pin": "{{LAST4_OF_PHONE}}", "expires_at": "2026-02-26T00:00:00Z" } // Invitee clicks link → prompted for PIN POST /v1/actions/act_.../consume { "pin": "4821" } // → 200: add user to team_xyz as member // Forwarded to stranger: 401 invalid_pin // Forwarded + correct PIN: 409 already_used
Pre-signed S3 URLs expire on a timer but can be shared freely within that window. If a user forwards a download link to a colleague (or it leaks via a browser history sync), anyone with the URL gets the file.
ExactOnce adds consumption semantics on top: the link is valid once, from the first click, regardless of TTL. Use it for invoices, contracts, medical records, or any file that shouldn't be downloadable twice.
// Generate download action (5-min TTL) { "payload": { "type": "file_download", "file_id": "invoice_2026_03.pdf", "user_id": "usr_abc123" }, "expires_at": "2026-02-19T00:05:00Z" } // Share link to user: /download?a=act_... // Download handler: POST /v1/actions/act_.../consume // On 200 → stream payload.file_id to user // On 409 → "This link has already been used" // On 410 → "This link has expired" // Forwarded link → 409 on second download
Expense approvals, contract sign-offs, deployment gates — any flow where "click approve" should trigger exactly one downstream action (send money, deploy code, release an asset).
With ExactOnce, the approval link is consumed atomically. Whether the approver double-clicks, or the email client pre-fetches the URL, or a webhook fires twice — the action fires once. The audit trail records who consumed it and when.
// Create approval action { "payload": { "type": "expense_approve", "amount": 1250.00, "expense_id": "exp_9f2c", "requestor": "usr_engineer" }, "expires_at": "2026-02-26T00:00:00Z" } // Manager receives: "Approve $1,250 → [link]" // Manager clicks → consume POST /v1/actions/act_.../consume // → 200: trigger payment for exp_9f2c // Manager double-clicks (slow connection) // → 409: payment already triggered. Safe. // Email client prefetch pings the link // → Use GET /verify, not POST /consume
Free-trial codes, referral rewards, gift vouchers, beta access keys. The classic failure mode: a user posts the code on Reddit and 5,000 people redeem it.
Create each code as an ExactOnce action. Consumed on first redemption. Use a PIN set to the user's email or phone suffix for personal codes. Use batch CSV creation to issue thousands of unique codes at once.
// Batch-create 1,000 unique codes via CSV POST /v1/actions Content-Type: text/csv payload_json,pin,active_at,expires_at "{\"type\":\"promo\",\"discount\":\"20_percent\",\"user_id\":\"usr_001\"}",,,2026-03-31T00:00:00Z "{\"type\":\"promo\",\"discount\":\"20_percent\",\"user_id\":\"usr_002\"}",,,2026-03-31T00:00:00Z ... // Each user gets their own unique link // /redeem?code=act_7f3k9mZn4pQ // On redemption: POST /v1/actions/act_7f3k9mZn4pQ/consume // → 200: apply 20% discount for payload.user_id // → 409: already redeemed // → 410: campaign expired
New account email confirmation, address change verification, phone number binding.
Common edge case: user clicks confirm, then clicks again from a different device.
Without exactly-once semantics, both requests can set verified = true — harmless here, but the pattern is broken.
More critically: a verification link that isn't invalidated after use can be replayed to re-verify a different email on the same account. ExactOnce prevents this.
// On signup, create verification action { "payload": { "type": "email_verify", "user_id": "usr_new", "email": "alex@company.com" }, "expires_at": "2026-02-20T00:00:00Z" } // User clicks "Confirm email" POST /v1/actions/act_.../consume // → 200: mark user.email as verified // → 409: already verified, show "you're good" // → 410: expired, re-send a fresh link // User changes email → old link no longer valid // Cancel old action, issue a new one DELETE /v1/actions/act_oldone
Set an active_at timestamp to schedule when the action
becomes consumable. Attempting to consume before that window returns a clean
409 not_active — no application-level scheduling logic needed.
Use cases: flash sale links that go live at midnight, early-access tokens distributed in advance, maintenance confirmation windows, scheduled RSVP closing.
// Create action window: opens Feb 20 at midnight { "payload": { "type": "flash_sale_access", "user_id": "usr_vip", "discount": "50_percent" }, "active_at": "2026-02-20T00:00:00Z", "expires_at": "2026-02-20T01:00:00Z" } // VIP tries at 11:59pm (too early) POST /v1/actions/act_.../consume // → 409 not_active // active_at: "2026-02-20T00:00:00Z" // At 12:00:01am — atomically consumed // → 200. Discount applied. Link dead. // At 1:01am (window closed) // → 410 expired
The honest comparison. Most alternatives cover part of the problem. ExactOnce covers all of it.
| Capability | Redis + TTL | Signed JWT | Auth0 / Clerk | ExactOnce |
|---|---|---|---|---|
| Exactly-once consumption | 〜 Race conditions | ✕ Replayable | 〜 Auth only | ✓ Atomic |
| Time-bounded expiry | ✓ | ✓ | ✓ | ✓ |
| Typed failure states | ✕ DIY | ✕ DIY | 〜 Partial | ✓ 4 states |
| Built-in audit trail | ✕ | ✕ | 〜 Auth only | ✓ |
| PIN protection | ✕ | ✕ | ✕ | ✓ |
| Batch creation (CSV) | ✕ | ✕ | ✕ | ✓ |
| Scheduled activation window | ✕ | ✕ | ✕ | ✓ |
| Zero infrastructure to manage | ✕ Redis cluster | ✓ | ✓ | ✓ |
| Not bundled with full auth platform | ✓ | ✓ | ✕ Full platform | ✓ Single purpose |