Invite a user

How it works

Use a Live administrator token, a Sandbox administrator/developer token, or a service-account key with users:invite. Service keys may invite requester members with no approvalGroupIds; admin invitations and approval-group grants require the administrator user token. In Sandbox, the same request creates a simulated invitation (delivery=simulated), with no email or real account. POST /v1/sandbox/invitations/{id}/accept simulates first sign-in and links its personId to a Sandbox-only identity. A new flow2act account receives an email with a temporary password and must set a personal password on first sign-in. Existing eligible accounts keep their password and accept by signing in again; ask them directly to sign in. flow2act returns no passwords.

The API checks active workspace access and either administrator user rights or a service-account users:invite scope before reserving or retrying an invitation. role describes the invited person, not the caller: role=admin cannot grant permission to send the request. Missing/invalid access tokens return 401; non-admin user tokens, inactive or foreign memberships, keys without users:invite and privileged service-key invitations return 403. Invitation validity: 7 days. Membership and direct approval-group grants activate only for the matching authenticated subject. Requester is the default role; admin must be explicit. Directory profiles remain independently editable. Reuse the same Idempotency-Key and input after uncertain results.

Service accounts require users:invite and can list/retry only invitations created by that same service account, including after key rotation. They cannot create admin invitations, assign approval groups or delegate credentials. Live invitations create real accounts; Sandbox invitations simulate provisioning and acceptance without sending emails.

Request body

Request essentials

Authorization

Bearer $FLOW2ACT_API_KEY

X-Organization-Id

Your workspace UUID

Idempotency-Key

Stable per operation; 8–128 characters