Invite a member into an organization
/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/organizations/{id}/invitesInvites an email into the organization. role_id is held on acceptance at node_id, the organization node (the default) or an office or team beneath it, for the effective_from to effective_to window when given; with no role_id the invitation admits a member holding nothing, which only the organization node allows (400 invite.malformed_assignment beneath it). Acceptance creates what is missing in one transaction: the identity, its Environment membership, the organization membership and the role. For someone who already holds an active membership in this Environment the invitation is a request to join (intent: grant): accepting is their consent, proven by their password or their own sign-in. Requires the identity.manage permission, or canopy:organization.manage at the organization or canopy:access.manage at the place for the organization's own administrators, and emits invite.created.
Authentication
AuthorizationJWT access token. Never send alongside X-API-Key: a request carrying both is refused.
env_identities.manageDeveloper ConsoleCreate, invite, edit, and remove identities and assign their roles. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.
production_identities.accessDeveloper ConsoleAccess identities in production Environments. Applies to users only, and only in an Environment marked production: its identities are real end users. API keys and identity principals are exempt.
Path Parameters
accountSlugstring Required The Account's slug. An unknown one answers 404.
appSlugstring Required The Application's slug within the Account.
envSlugstring Required The Environment's slug within the Application.
idstring Required Request body
application/json
emailstring Required Email to invite. Works for people with no identity in this Environment — one is created when they accept.
role_idstring Optional The role the person holds on acceptance, at `node_id`. Optional at the organization node, where accepting admits a member with no role; required for a place beneath it.
node_idstring Optional Where the role is held: the organization node (the default) or an office or team beneath it. Accepting admits the person to the organization either way.
effective_fromstring · date-time Optional When the role starts to count (ISO 8601). Copied onto the assignment the invitation grants; needs a role.
effective_tostring · date-time Optional When the role stops counting (ISO 8601), after `effective_from`. Copied onto the assignment; an invitation whose window has ended by acceptance is refused with `400 invite.window_ended`.
first_namestring Optional last_namestring Optional send_emailboolean Optional Set false to skip the email and deliver the returned accept URL yourself.
Responses
application/json
dataIdentityInviteResponseDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
application/json
errorApiErrorBodyDto
Errors
When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs.
account.capability_requiredForbiddenThe signed-in user's administrator roles do not grant the capability this endpoint requires.
Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.
environment.production_identities_forbiddenForbiddenThe Environment is marked production and the caller is a user without production identity access.
Manage these people in the Admin Workspace, or ask an administrator to grant the Production Support role, then retry.
Returned object
curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/value/applications/value/environments/value/organizations/value/invites" \ -H "Authorization: Bearer $CANOPY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "string", "role_id": "string", "node_id": "string", "effective_from": "2026-04-20T12:00:00.000Z", "effective_to": "2026-04-20T12:00:00.000Z", "first_name": "string", "last_name": "string", "send_email": true }'
{ "data": { "id": "string", "email": "string", "intent": "activate", "first_name": "string", "last_name": "string", "name": "string", "role_id": "string", "node_id": "string", "node_name": "string", "organization_node_id": "string", "effective_from": "2026-04-20T12:00:00.000Z", "effective_to": "2026-04-20T12:00:00.000Z", "has_initial_assignment": false, "status": "pending", "expires_at": "2026-04-20T12:00:00.000Z", "invited_by": "string", "invited_by_identity_id": "string", "created_at": "2026-04-20T12:00:00.000Z" } }
Tell us how we can improve this guide.