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, or 24 hours for password_reset; 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

The role the invitation grants at `node_id`. Required with a `node_id`, except an organization node, where an invitation may admit a member with no role.

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.

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`.

Responses

application/json

  • dataApiIdentityInviteResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

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,
    "effective_from": "2026-04-20T12:00:00.000Z",
    "effective_to": "2026-04-20T12:00:00.000Z"
  }'
Response
{
  "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",
    "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