Identities Quick Start

Two ways to invite

This Quick Start covers the Console's Invite & Assign flow because it takes the invitee from zero to permissions-ready in one step. The Console has a second invite path too, useful when you don't yet know what role the person needs.

Invite (Identities → Overview): the invite carries no role. Accepting gives the person access to the Environment, and you assign roles later.

Invite & Assign (Identities → Overview): the invite carries a role at a hierarchy node, so accepting grants the identity, its access to the Environment and the role in one step. This is the path the Quick Start walks through.

Account administrators can also invite people from the Admin Workspace; see Send and Manage Invitations.

See the three-layer model on the Identities overview →

Using the Console

In the Developer Console, Identities → Overview (under Access Control) holds a card for each way to add people to the active Environment. Invite sends an email-only invite with no role attached. Invite & Assign, covered on this page, pairs the invite with a role assignment in a single step. Create Identity skips the email entirely and writes the identity row immediately; see the Console Create page for that flow.

Application: Developer Console
Path: Access ControlIdentitiesOverview
Opens with: env_identities.manage Invite, create, import, edit, and remove identities in the Environment, and assign their roles.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Invite an identity

Open Identities → Overview from the left nav under Access Control. It's scoped to whichever Environment is active in the Application and Environment switcher.

Click the Invite & Assign card. The invite dialog opens.

Enter the email address, first name, and last name for the new identity.

Pick a Role and the Node the assignment lands on. In a flat Environment the node is fixed to the root and shown as Applies at. In a hierarchy-enabled Environment, the node picker shows the Environment's tree.

Optionally pick an Application; the list shows your OAuth clients that have an invite redirect URL. When set, the invite link in the email points at that client's invite_redirect_url, so the recipient lands on your own accept page. When left blank, the link goes to the Environment's Auth email links land on origin (Authentication → Sign-in methods) at /accept-invite if one is set, otherwise to Canopy's hosted /auth/accept-invite page.

Click Send Invite. The recipient gets an email with a link to accept. As soon as they accept, the identity can sign into the Environment and the role is live. Accepting does not restore a membership someone was removed from; bring them back with Add from directory instead.

Other entry points

Invite: email-only invite, the same dialog without the role + node fields. Use this when you want to add the person now and decide their access later.

Create Identity: writes the identity row immediately with no email ceremony, optionally with a starting password. See the Console create page.

Invites tab on Identities → Directory: every invitation is listed here. Open one to resend or revoke it.

First time setting up?

On a fresh Environment (every new Application is seeded with an empty Development and Production Environment), Access Control → Overview shows a banner that begins You haven't invited any users or assigned them roles yet. Click Complete Invite & Assign Users Setup to open the Setup guide, a floating checklist that opens on its first unfinished invite or assignment step. Each step links directly to the right page and offers help alongside, so you don't have to bounce between docs and the Console to figure out where to click next.

What the guide walks you through:

Invite Identities

Assign Role to Identity

Inviting many at once? Use the Console's CSV import wizard →

What the recipient sees

Once you click Send Invite, the recipient receives an email in the Environment's branding that names the Application and carries an Accept invitation button.

Their flow

The email arrives within a few seconds. For someone new to the Account, the subject reads "You're invited to {Application name}". Someone who already has an identity in the Account gets "You've been added to {Application name}" instead, with a Confirm invitation button. Someone already in this Environment, invited into an organization, gets "Join {organization}", listing the role, the place, any dates and who sent it.

Clicking Accept invitation takes them to the accept page: the OAuth client's invite_redirect_url when an Application was selected, otherwise the Environment's auth-link origin at /accept-invite if one is set, else Canopy's hosted /auth/accept-invite page.

Someone new confirms their first and last name (pre-filled from the invite) and sets a password. Passwords go through a HaveIBeenPwned breach check; breached passwords are rejected up front. Someone who already has an identity enters their existing password instead. Joining an organization, the page lists what the invitation offers and states that accepting adds the organization to their account; they confirm with their password, or accept while signed in, and an organization that requires single sign-on, or a person with a second factor enrolled, asks them to sign in first.

On submit, in one transaction, the identity is created (or completed, if it existed without a password), the password is stored as an Argon2id hash, the identity gets access to the Environment, it is admitted to the organization the invitation names, and any role assignment attached to the invite is created with its dates.

The accept link is single-use: once accepted, the invite reads accepted and the link stops working.

On Canopy's hosted page, the confirmation offers Sign in when a Sign-in URL is set: the OAuth client's when an Application was selected, else the Environment's (Authentication → Sign-in methods). It opens the page in your app that starts a sign-in, so the new identity is signed in without hunting for your app. With neither set, the page offers no link.

Invites expire after 7 days. An expired invite can be sent again from the Console, which issues a fresh link with a new 7-day window.

Managing pending invites

Open Identities → Directory from the left nav and switch to the Invites tab to see every invitation that hasn't been accepted yet, plus history for accepted, expired, and revoked ones. Click any row to open its detail drawer.

From the invite drawer

Resend Invite (pending) or Send a new invitation (expired) generates a fresh token, resets the expiry (7 days, or 24 hours for a password reset sent through the API), and sends the email again. There's a 5-minute cooldown to avoid accidental flooding.

Revoke Invite (pending only) immediately invalidates the token. The recipient's existing link lands on a page saying the invitation has expired. Useful when you sent to the wrong address or the recipient never plans to accept.

Accepted and revoked invites stay in the list as read-only history.

To re-invite someone whose invite was revoked, send a brand-new invite: the old row stays in history and the new one is independent.

Using the API

You can also invite identities through the API instead of using the Console. Use this when you're provisioning users in bulk, syncing from an HR or directory system, or wiring sign-up into a self-service flow on your own site. Each API key is scoped to one Environment: POST /api/v1/identity-invites creates the invitation, and any role + node attached to it, in that Environment and nowhere else.

Endpoint

POST /api/v1/identity-invites

Authenticate with your API key in the X-API-Key header.

Example

Send the recipient's email, first name, and last name, with an optional initial role and node, in the request body:

{
  "email": "regional.manager@example.com",
  "first_name": "Pat",
  "last_name": "Lee",
  "role_id": "5e1f2a3b-4c5d-4e6f-7a8b-9c0d1e2f3a4b",
  "node_id": "0aa1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c"
}

The response returns the created invitation with its id and an accept_url. Nothing is granted until the recipient accepts; until then only the invitation exists, in the pending state. On accept, the identity gets access to the Environment and the pre-attached assignment takes effect immediately. For mass invitations, the same surface exposes POST /api/v1/identity-invites/bulk-create for up to 200 invites per call, reporting each row's success or failure.

View full API reference →

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.