Invitations

Organization owners and admins add teammates to the Tokeflow Dashboard by sending invitations. The invitee receives an email with a link that carries a signed, single-purpose invitation token. The three endpoints on this page power that landing flow: the Dashboard UI first verifies the token to show who is inviting whom and into which role, then the invitee either accepts (creating a user account first, when they don't have one yet) or declines.

Accepting an invitation grants the invitee membership in the organization with the role chosen by the inviter — owner, admin, or viewer. Roles and what they can see are described in Organizations and merchants.

How the flow works

Always verify before rendering an accept form: the is_new_user flag in the verification result tells you whether to ask the invitee for a password (new account) or just confirm (existing account).

The verification result object

GET /api/v1/invitations/verify returns this object. Only valid is always present; the descriptive fields are nullable and are what the Dashboard shows on the invitation landing page.

Endpoints

GET/api/v1/invitations/verify

Verifies an invitation token and returns the details needed to render the invitation landing page: who invited, into which organization and role, when the invitation expires, and whether the invitee needs to create an account.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/invitations/verify \
  --data-urlencode "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Example response — 200 OK

{
  "valid": true,
  "email": "jane@acme.com",
  "organization_name": "Acme Digital",
  "role": "admin",
  "inviter_name": "Carlos Prado",
  "expires_at": "2026-08-19T12:00:00.000Z",
  "is_new_user": true
}

Example response — 200 OK, expired token

{
  "valid": false,
  "email": null,
  "organization_name": null,
  "role": null,
  "inviter_name": null,
  "expires_at": null,
  "is_new_user": false
}

POST/api/v1/invitations/accept

Accepts an invitation and grants the invitee membership in the organization. When the invitation is for a new user (is_new_user: true in the verification result), include password and confirm_password — the user account is created with that password as part of the accept.

Request fields

Example request — new user

curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
    "name": "Jane Doe",
    "password": "mySecureP@ss123",
    "confirm_password": "mySecureP@ss123"
  }'

Example request — existing user

curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'

Response — 201 Created

A successful accept returns 201 Created with an empty body. The invitee can now sign in to the Dashboard with their email and password.

POST/api/v1/invitations/decline

Declines an invitation. The token is consumed and the invitee is not added to the organization; the inviter can always send a new invitation later.

Request fields

Example request

curl -X POST https://api.tokeflow.com/api/v1/invitations/decline \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'

Response — 201 Created

A successful decline returns 201 Created with an empty body.

Errors

The most common cases for these endpoints:

See Errors for the general error format used across the API.

Related

• Dashboard authentication — sign in after accepting an invitation.
• Organizations and merchants — how organizations, roles, and merchants fit together.
• Audit logs — membership changes appear in the organization's audit trail.