Identities
End users of your application: Account-level rows that hold credentials and federation hints, given access to specific Environments through memberships and permissions through role assignments.
Overview
An identity represents a single end user of your application. Each identity belongs to exactly one Account: the same email can exist in multiple Accounts as completely separate identities, and authentication always requires an Account context. An identity carries an email, first and last name, optional metadata, and an optional external_id for federated identities. Identities are the subject of the RBAC system: every permission check resolves whether an identity has a permission at a given node in a given Environment. An identity row can exist before the person ever signs in, for example when an admin pre-provisions accounts for a launch, and stays around after they're deactivated, so the assignment history is preserved.
Scope
Identities have three layers
Unlike permissions and roles, an identity isn't a single per-Environment record. The same identity reaches across your Account through three layers, and each layer answers a different question.
This is why Promote Configuration to… copies an Environment's configuration (permissions, roles, hierarchy) but not its identities or their assignments: those are operational state you manage per Environment.
Layers in practice
Each layer is a separate row type. The table maps the concept to the concrete row and where you manage it in the Developer Console.
| Layer | Row type | Where to manage | What it holds |
|---|---|---|---|
| Account | Identity | Identities → Overview: Invite, Invite & Assign, Create Identity or Import CSV creates it | Email, name, optional metadata and external_id, is_active. The directory of every end user in your Account; this row exists independently of any Application or Environment. |
| Environment access | Environment membership | Added by the same Overview cards or Add from directory; removed from the identity drawer on Identities → Directory | A row linking one identity to one Environment. Decides which Environments the identity can sign into. No role attached: what they can do inside an Environment is granted by role assignments. |
| Environment role | Role assignment | Identities → Directory (identity drawer), the Assign roles card on Identities → Overview, or a node on Hierarchy | A row linking identity + role + hierarchy node, with optional start/end dates. Decides what the identity can do in that Environment and where in the hierarchy that access applies. |
An identity can sit at the Account layer with no Environment access and no assignment: that's a directory-only row, useful for pre-provisioning, federated lookup, or staged onboarding. Granting Environment access lets the person sign into that Environment; adding role assignments grants them concrete access. With organizations on, a person's membership in an organization is its own record beside these layers, created by a grant at the organization node or by accepting an invitation into the organization, and required for any role beneath it; see Enable Organizations and Manage Members. In a production Environment the Console's identity pages stop listing people for anyone without production_identities.access, and they are managed in the Admin Workspace instead (see Console and Workspace).
Lifecycle
Each identity row has an is_active flag, which the Console shows as Active or Inactive. The flag is on the Account-level row, so it applies in every Environment. Erasure is a separate, final state:
Deactivation and erasure are Account-wide, so both are done in the Admin Workspace (see Add and Manage Identities), never from one Environment. Directory sync deprovisions a person from the Environment its directory serves, not Account-wide. To cut someone off from one Environment, remove them from it: Remove from environment in the Console, or DELETE /api/v1/identities/:id. Deactivation is reversible and keeps history; erasure is not. There is no hard delete.
Authentication
Identities authenticate two ways. Hosted login via OAuth2/OIDC (/oauth/authorize) is the standard path: your app redirects, Canopy handles the password ceremony, and your app exchanges the returned code at /oauth/token for a signed JWT. Direct API (/v1/identity/auth/*) is the lower-level surface for apps that want to own the login UI; the same JWT comes back. Password validation, email verification, password reset, and session management run on the platform either way. Your app never stores credentials when you delegate authentication to Canopy. Alternatively, you can handle authentication yourself and use Canopy purely for authorization.
How to add identities
Pick the path that matches how identities enter your system. The Console options are best for admin-driven onboarding handled by a person clicking through the UI; the API options are best for automated, scripted, or self-serve flows kicked off by your own backend. Each card links to a walkthrough.
Console invite
Admin clicks Invite or Invite & Assign in the Console; Canopy emails the invitee a link to set their own password.
Console create
Admin opens the Create Identity dialog; the identity row is written immediately, with an optional starting password.
Console CSV import
6-step wizard for batch provisioning from a CSV: choose a mode, upload, map columns, preview, submit, and review the results. Rows are sent 200 per request.
API invite
Programmatic invitation flow: your backend issues invites, Canopy sends the email (or hands back the link for self-delivery).
API create
Server-to-server identity creation through the public API, with no email and no acceptance ceremony.
Tell us how we can improve this guide.