Skip to main content
An invitation is a pending offer to join your organization. It carries a target email, a target role, and a one-time secret token. When the recipient accepts the invite (by following the URL you build with that token), their organization_members row is created and member.joined fires.
Invitations expire automatically. The expires_at field on every invitation tells you when. Expired invitations cannot be accepted — re-invite the user with a fresh POST /team/invitations.

​
The invitation object

FieldTypeNotes
iduuidInvitation id. Use for GET/DELETE.
emailstringValidated as an email. The recipient must sign in with this address.
role_iduuidThe role the recipient will hold once accepted.
rolestringDisplay-only role name.
statusenumOne of pending, accepted, declined, expired, revoked. List/GET only return pending.
invited_byuuid ∣ nullThe user that issued the invite. null for invitations created by org-scoped API keys.
expires_attimestampAfter this time the token stops working.
created_attimestampWhen the invitation was issued.
updated_attimestampLast status change.

​
Create an invitation

POST /team/invitations with the recipient’s email and the target role id. The response returns the new invitation and a one-time secret token — this is the only time the token is shown, so capture it now.
cURL
curl -X POST https://api.awardee.dev/v1/team/invitations \
  -H "Authorization: Bearer aw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'
Build the accept URL with the returned token: 
https://app.awardee.dev/invite/accept?token=<token>
Treat the token as a secret. Anyone who possesses it can accept the invitation as the named email address (after Sign-In). Send it via a side channel you trust (transactional email, in-app DM), and do not log it.
POST /team/invitations is idempotent — pass an Idempotency-Key header to make safe retries. See Idempotency.

​
List pending invitations

cURL
curl https://api.awardee.dev/v1/team/invitations \
  -H "Authorization: Bearer aw_live_…"
Returns only invitations with status = "pending". Already accepted/declined/expired/revoked rows are not surfaced — query the audit log if you need full history.

​
Get one

cURL
curl https://api.awardee.dev/v1/team/invitations/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…"

​
Cancel an invitation

DELETE /team/invitations/{id} revokes a pending invitation. Once revoked, the token stops working — even before its expires_at. Fires invitation.revoked.
cURL
curl -X DELETE https://api.awardee.dev/v1/team/invitations/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_…"
Returns 204 No Content. Already-accepted, declined, expired, or revoked invitations cannot be revoked again — the endpoint returns 409 conflict in that case.