Every invite issued through this endpoint belongs to the Environment the API key is scoped to — there is no Account-tier path on the public API. If you need a directory-only invite that doesn't attach to an Environment (federated/SSO pre-staging, for example), use the dashboard's Tenant > Identities → Invite surface, which writes through a portal endpoint that allows environment_id to be NULL.

Auth: API key (X-API-Key) OR portal user JWT (Authorization: Bearer). Either way, the principal needs identity.manage in the target Environment.

Request

Response

accept_url comes back on every successful create — store it if you want to deliver the link yourself, or just discard it if Canopy is sending the email. has_initial_assignment reflects whether you passed role+node; it's the cheap way to tell at a glance whether this invite turns into a permission grant on acceptance.

Auth: Same as single send — API key or user JWT with identity.manage in the target Environment. Authorization is checked once upfront, not per row.

The body wraps an invites array of standard send payloads. Each item takes the same fields documented above (email, first_name, last_name, optional role_id + node_id, optional client_id, optional send_email).

Every successful response — full success or partial — has the same body shape: a summary with totals and a results array with one entry per input row, ordered by index. Successful rows include the created invite plus its own accept_url so self-delivery callers don't have to make a second call.

200 OK when every row succeeded. 207 Multi-Status when at least one row failed. The body shape is identical either way — branch on the summary.failed count, not the HTTP status, if you want a single code path.

Request

Response — every row succeeded (200 OK)

Response — mixed outcomes (207 Multi-Status)

Every result entry carries an index matching its position in the request array. Successes carry data (the created invite plus its accept_url, in the same shape as the single-send response). Failures carry input (the original row, echoed back so you can correlate without bookkeeping) plus an error object with a stable machine-readable code and a human message.

Anything else — auth failure, the database becoming unreachable mid-batch, an invalid org context — short-circuits the whole request as a normal error response (401, 403, 500) rather than a per-row failure. Per-row failures are reserved for business errors that are intrinsically about the row's data.

Set send_email: true (or omit it). Canopy queues a templated email through its mail provider — currently Mailgun — and renders the invitee's first name, the inviter's name, and the tokenized URL. You still receive accept_url in the API response so you can log it for auditing or display it in your dashboard, but you don't have to do anything with it.

Set send_email: false. Canopy creates the invite but skips the email entirely. The accept_url in the response is the only copy of the tokenized link — you must capture it and own delivery (your own transactional email, in-app notification, Slack DM, QR code, anything). If you lose the URL before delivering it, you'll have to call resend to get a fresh one.

When to choose self-delivery. Pick self-delivery when you need to brand the email yourself, batch invitations into a digest, route through a different mail provider, or attach the invite to an existing onboarding email you already send. Otherwise let Canopy handle it — the default email gets the link in front of the user with no extra code.

Auth: Same as create — API key or user JWT with identity.manage.

Auth: Same as create — API key or user JWT with identity.manage.

Revoking is destructive — there's no undo. Only pending invites can be revoked; calling DELETE on an accepted, expired, or already-revoked invite returns 400 InviteNotPending. To re-invite the same email after revoking, just call create again — the duplicate guard only counts pending invites.

Sample error response