# flow2act · Invite a user

Invite a person with a login, organization role and optional approval groups.

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.

## POST /v1/organization/invitations

Authentication: restricted integration key (scope: users:invite) or flow2act sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- locale (string, optional): max length 35
- displayName (string, required): min length 1 · max length 120
- email (string, required): email · max length 128
- role (string, optional): requester | admin · default "requester"
- approvalGroupIds (array, optional): max items 50 · default []

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flow2act.com/v1/organization/invitations" \
  -H "authorization: Bearer $FLOW2ACT_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-invite-user-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": "alex@example.com",
  "role": "requester",
  "approvalGroupIds": []
}'
```

## Response excerpt

```json
{
  "status": "invited",
  "delivery": "temporary_password"
}
```

Source: /docs/invite-user
Full schemas: /docs/openapi.json