Invite a user

Sends an invitation email to a new user, provisioning their role and group access within the specified tenant before they have an Esper account.

Use this endpoint to onboard new team members to an Esper enterprise programmatically — the invite flow handles identity provider registration via the connection_id and assigns the user's role and group scope in a single step.

About Invite a User

Esper's invite system separates access provisioning from account creation. When you call this endpoint, Esper generates an invitation record in the tenant and can optionally trigger an invitation email via the identity provider. The invited user receives a link to complete registration; upon acceptance, their account is created with the role and group access defined in the meta.profile block. This is the recommended way to add users to a tenant in preference to direct user creation.

Key Fields / Request Body

email — (required) the email address of the person being invited

meta.profile.role — (required) the role to assign: Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User. Use AuthZ Role User when assigning a custom RBAC role defined in Esper's authorization service — this role type enables fine-grained scope control tied to a specific authz_role_id

meta.profile.enterprise — (required) the tenant UUID; must match enterprise_id in the path

meta.profile.groups — list of group UUIDs to scope access; required for Group Admin and Group Viewer roles

meta.profile.authz_role_id — UUID of the custom RBAC role to assign; required when role is AuthZ Role User. This binds the user to a specific scope set managed by Esper's AuthZ service, allowing more granular access control than the built-in fixed roles

connection_id — the identity provider connection to use for the invite flow

invitation_url — returned in the response; the link the user follows to complete registration

Common Use Cases

Onboarding a new IT admin or support engineer to a tenant

Granting a new Group Admin scoped access to a specific device group

Automating user provisioning workflows where users are invited in bulk from an HR or directory system

Best Practices

Always set meta.profile.groups when the role is Group Admin or Group Viewer — the invite will be created but access will be undefined without it

Validate that meta.profile.enterprise matches the enterprise_id path parameter before submitting

Store the returned id (invite ID) immediately; you will need it to cancel the invite via DELETE /authn2/v0/tenant/{enterprise_id}/invite/{invite_id} if the user shouldn't have been invited

Use GET /authn2/v0/tenant/{enterprise_id}/invite to check whether a pending invite for an email already exists before re-sending

Workflow

Determine the new user's email, intended role, and group scope

POST to this endpoint with the meta.profile block fully populated

Store the returned invite id for auditing or future cancellation

The user receives an email and follows the invitation_url to complete account creation