1. Docs
  2. API Reference
  3. Create an invite

Create an invite

POST/api/v1/identity-invites

Creates a single identity invite in the active Environment and returns it along with a tokenized accept_url. The effective intent is derived server-side from existing identity state — a net-new email becomes activate, an existing identity without active access becomes add_to_app, and password_reset is honored only for an existing identity. An optional role_id + node_id pair (both or neither) seeds an initial role assignment applied at acceptance. Invites expire after 7 days; the email is sent unless send_email: false, in which case the caller delivers accept_url itself. A duplicate pending invite for the same recipient returns 409.

Authentication

Bearer TokenAuthorization Option A

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Request body

application/json

client_idstring Optional

OAuth client ID — determines which app the invite links to. If omitted, uses Canopy hosted fallback.

intentenum Optional

Optional. `activate` (default) creates a net-new identity OR — if an identity with this email already exists in the Account but has no active membership in this App — auto-derives an `add_to_app` invite that adds them to this App without touching their existing password. `password_reset` is the explicit admin-driven credential-rotation flow for an existing identity; it cannot carry a role/node assignment. The legacy `onboard` value is accepted and treated as `activate`.

one of "activate" · "password_reset" · "onboard"

emailstring Required
first_namestring Optional

Required for `activate`. Ignored for `add_to_app` (the existing identity's name wins) and for `password_reset`.

last_namestring Optional

Required for `activate`. Ignored for `add_to_app` and `password_reset`.

role_idstring Optional

Role ID — required if node_id is provided

node_idstring Optional

Node ID — required if role_id is provided

send_emailboolean Optional

Whether Canopy should send the invite email. Set false to suppress delivery and handle it yourself — the API response includes accept_url with the tokenized link. Defaults to true.

Responses

application/json

  • dataApiIdentityInviteResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

ApiIdentityInviteResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/api/v1/identity-invites" \
  -H "X-API-Key: $CANOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "string",
    "intent": "activate",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "role_id": "string",
    "node_id": "string",
    "send_email": true
  }'
Response
{
  "data": {
    "id": "string",
    "email": "string",
    "intent": "activate",
    "first_name": "string",
    "last_name": "string",
    "name": "string",
    "role_id": "string",
    "node_id": "string",
    "environment_id": "string",
    "environment_name": "string",
    "has_initial_assignment": false,
    "status": "pending",
    "expires_at": "2026-04-20T12:00:00.000Z",
    "invited_by": "string",
    "created_at": "2026-04-20T12:00:00.000Z",
    "accept_url": "string"
  }
}
 Related endpoints
GETList invites
GETGet invite summary
POSTBulk-create invites
POSTResend an invite
DELETERevoke an invite
 Was this page helpful?

Tell us how we can improve this guide.

Canopy