Read what an invitation link offers, before accepting it

What the accept surface shows before the invitee commits (AC-124).

The token is the secret from the invitation email. This is what builds the "join Northwind Support as an editor" screen: it names the workspace, the role on offer, who invited them and when the link runs out.

Read acceptable before offering a join button. state says why it is false: expired, revoked, or accepted because someone already used it.

password_required decides which screen comes next. true means the invitee has no account yet and should be sent to the claim route to create one. false means they already have one and should sign in and accept. null means it could not be determined, and the safe move is to send them to sign in, which is recoverable in one step.

A token that does not match anything is refused with invitation_unknown and nothing else. No address, no workspace, no role. Reading a 404 here as "wrong workspace" is a mistake: it means the value is not a live token.

Public, and therefore hardened as an enumeration surface: a value that does not hash to a stored digest gets invitation_unknown carrying no address, no workspace, no inviter, no role and no expiry. Everything this route knows it declines to say until the caller has proved they hold the credential it is about.

Expired, revoked and consumed are named here rather than flattened into unknown, and that is a deliberate reading of the anti-oracle rule. The rule protects against a caller who does not hold a token; such a caller cannot reach these branches at all, because reaching them requires a value that matches a SHA-256 digest of a 256-bit CSPRNG secret. Flattening them would defend against an attack that already requires the credential, at the cost of AC-112's three distinct answers and AC-125's nine distinct surfaces: an invitee holding a genuinely expired link would be told only that their link is "not valid", which is the shared message FR-103 exists to forbid.

Charged against the acceptance budget, refunded once the token resolves. It shares that budget rather than taking a third scope because it is the same actor doing the same thing one step earlier, and separate budgets would let a guesser spend both. An invitee following their own link pays nothing; a caller working through the keyspace pays for every miss.

Access: no credential.

Path Parameters

Response Body

curl -X GET "https://example.com/v1/invitations/string"

{  "state": "pending",  "acceptable": true,  "email": "sam.okafor@northwind.example",  "role": "editor",  "expires_at": "2026-08-21T10:04:00+00:00",  "workspace_name": "Northwind Support",  "invited_by": {    "display_name": "Dana Osei",    "email": "dana.osei@northwind.example"  },  "password_required": true}