Create Client Invite

POST /v1/endpoints/{uuid}/rbac/clients/invites

Issue a one-time invite link an end user redeems to become an RBAC client of this endpoint. The link opens on the endpoint's own hostname (https://<endpoint host>/_tunnel_auth/register?invite=<token>), on a page that looks like the endpoint's sign-in page: the invitee chooses a username and password (when the endpoint offers password sign-in) or signs in with one of the endpoint's OAuth providers, and is then signed in. The link works once, only on this endpoint, until it expires.

OAuth / SSO redemption needs the provider account's email to be the invite's email (compared trimmed and case-insensitively); an address the provider reports as unverified, or none, is refused. An invite without an email can therefore only be redeemed with a username and password.

The endpoint's registration policy applies when the invite is redeemed: with self-registration off the invite is refused ("Registration is closed"); with Requires approval the user is created pending until you activate them; with Invite only (invite_only: true) the invite is your approval, so there is no approval step, whatever auto_approve says; with email verification on, a confirmation link (valid 24 hours) is emailed to the invite's address and the user gets access once they open it. The allowed / blocked email domains and the password requirements apply too.

One invite sends at most one confirmation email every 2 minutes and 5 a day; past that the invitee's page says "Already sent — check your inbox" and no email is sent. A username that is already taken on the endpoint is refused before any email goes out. See Sign-in protection for the limits on the invite and login pages.

This call does not email the invite: hand the link to the user yourself. The token is shown only in this response; ngris stores only its hash.

Path parameters

uuid string (uuid) Req
The endpoint's uuid from /endpoints.

Request body

email string
The invitee's email address. Optional, except when the registration policy requires email verification: the confirmation email goes to this address.
display_name string
Pre-fills the new client's display name.
expires_in_hours int
Hours until the invite expires. Default 72 when omitted or ≤ 0; capped at 8760 (1 year).
role_uuid string (uuid)
One of this endpoint's roles (RBAC config): the role the invitee gets. Omitted: the invitee gets the endpoint's default roles and the registration policy's Default Role when they redeem the invite. Required when the endpoint has neither (no role marked default, no registration Default Role): such an invitee could not access anything.

Response (200 OK)

uuid string (uuid)
The uuid of the created invited-status placeholder client.
invite_token string
The single-use token in the link. Shown only here.
invite_url string
The link to give the invitee: https://<endpoint host>/_tunnel_auth/register?invite=<invite_token>. Treat it as opaque and hand it to the user as-is.
email string
Echo of the supplied email (empty string if none).
display_name string
Echo of the supplied display name.
expires_at datetime
Invite expiry. Past this time, redemption fails.
status string
Always invited for a freshly created invite.
role_uuid string (uuid)
The invite's role, when one was given.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Errors

400 Bad Request
Malformed JSON request body; no email while the registration policy requires email verification; or no role_uuid while the endpoint has no default role and no registration Default Role ("Choose a role for this invite…"). The response's fields names the field.
401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks the endpoints:write permission in the active account.
404 Not Found
Endpoint doesn't exist or doesn't belong to the calling account; or role_uuid is not one of this endpoint's roles.
409 Conflict
A user of this endpoint already has this email address.
Request
curl -X POST "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/rbac/clients/invites" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{ "email": "alice@example.com", "display_name": "Alice", "expires_in_hours": 24, "role_uuid": "019b5726-1a2b-7c3d-8e4f-5a6b7c8d9e0f" }'
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") inv = client._post_raw( "/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/rbac/clients/invites", {"email": "alice@example.com", "expires_in_hours": 24}, ) print("Send to user:", inv["invite_url"])
Response — 200 OK
{ "uuid": "019b5725-4607-7367-bf7d-30155d363ab9", "invite_token": "a1b2c3d4...", "invite_url": "https://app.example.com/_tunnel_auth/register?invite=a1b2c3d4...", "email": "alice@example.com", "display_name": "Alice", "expires_at": "2026-04-30T13:00:00Z", "status": "invited", "role_uuid": "019b5726-1a2b-7c3d-8e4f-5a6b7c8d9e0f" }
Was this helpful?
On this page
Create Client Invite
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard