Accept an invitation as the signed in user

Cases 2, 3 and 4: join the workspace as the identity that signed in.

Call this once the invitee has signed in. It consumes the invitation and writes their membership, and the response says which workspace they are now in and at what role.

The signed in address must be the invited address. A different one is refused with invitation_address_mismatch, and the refusal names the address the invitation was issued to so the screen can offer to sign in as that person instead.

An invitee with no account at all cannot use this route. Send them to POST /v1/invitations/{token}/claim instead.

Accepting is safe to attempt when the person is already a member. already_a_member is then true, and promoted says whether the invitation raised their role. An invitation never lowers a role: an existing owner invited as a viewer stays an owner, and role in the response is the role they actually hold now.

A token can only be used once. A second attempt is refused with invitation_consumed, and that is also what the loser of two simultaneous acceptances sees. Nothing is written unless every check passes, so a refusal leaves the invitation usable.

The order of checks is the order of what each refusal costs to be wrong about, and every one of them happens before anything is written (FR-104): the token resolves, the identity is verified, the invitation is acceptable, the address matches, the issuer still holds the authority they delegated, and only then does one transaction consume the invitation and write the membership.

Access: Authorization: Bearer carrying a realm access token. An API key is refused here with api_key_identity_only: this operation answers for a person, and a key acts in one workspace.

Path Parameters

Response Body

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

{  "workspace_id": "9e2b6c14-3d08-4a7f-b512-8c0d4e6a1f93",  "role": "editor",  "already_a_member": false,  "promoted": false}