API Invite

Every invite issued through this endpoint belongs to the Environment the API key is scoped to. The public API has no Account-wide invite; account administrators invite people into the Account-wide directory from the Admin Workspace (see Send and Manage Invitations).

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. invited_by is the inviting user, or null when an API key sent the invite; invited_by_identity_id is the organization's own administrator who sent it with their identity token, whose standing acceptance re-checks. organization_node_id names the organization the invitation joins (null outside one), node_name the place its role is held at, and effective_from / effective_to the window copied onto the role.

Auth: Same as single send: an 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, so 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) 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 sends a templated email through its mail provider with the invitee's first name, the Application's name, and the tokenized link, which expires in 7 days, or 24 hours for a password_reset invite. 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, resend returns a fresh one, but resend always emails the invitee too.

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: an API key or user JWT with identity.manage.

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

Revoking is destructive, and there's no undo. Revoking an accepted invite returns 400 invite.not_pending. An expired invite can be revoked too, and revoking an already-revoked invite answers 204 again with no change. To re-invite the same email after revoking, just call create again: the duplicate guard only counts pending invites.

Sample error response