Create RBAC Client

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

Provision a new RBAC client (end user) for an endpoint. The client can then authenticate using whichever credential type you supply: username + password, bearer token, or OAuth identity (matched on the next OAuth login). Default roles configured on the endpoint are auto-assigned to the new client.

Credential methods are gated by the endpoint's enabled auth methods: passing a password when password auth is disabled returns 400. Set auto_generate_token: true instead of supplying a token to have the platform mint a secure random token — returned once in the response.

Plan-gated: requires the endpoint RBAC entitlement on your plan. Identifier collisions across email, username, or OAuth identity return 409.

Path parameters

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

Request body

identifier string Req
Stable identifier (canonicalised lowercase). Often the user's email.
display_name, email string
Human-readable name and contact email. Optional.
username string
Username for password auth. Set together with password.
password string
Plaintext password. bcrypt-hashed before storage. Requires the endpoint's UsernamePassword auth method to be enabled.
auto_generate_token boolean
Mint a secure random bearer token. Returned only once in the response. Mutually exclusive with token.
token string
Pre-set bearer token. Hashed before storage; never retrievable.
identities array
OAuth identities to pre-link, each {provider, subject}. Requires the endpoint's OAuth/SSO auth method to be enabled. Use when migrating an existing OAuth user from another system.
status string
active (default when empty) | invited | disabled | revoked.
metadata object
Free-form JSON tags. Useful for grouping by team/department.
registration_source string
Defaults to admin. Internal callers can set self, invite, or sso.

Response (200 OK)

The created client (same shape as a list entry) plus, when auto_generate_token: true:

generated_token string
The freshly-minted bearer token: et_ followed by 64 hex characters. Show once, store securely; not retrievable later. Only present when a token was auto-generated.

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.

Endpoint-default roles, if any, are auto-assigned to the new client; query /rbac/memberships to see them (they are not embedded in this response).

Errors

400 Bad Request
Unknown body fields (strict decoding), missing/invalid identifier, invalid status, or a credential for a sign-in method the endpoint has off in its enabled_auth_methods: bearer token authentication is not enabled for this endpoint (token or auto_generate_token), username/password authentication is not enabled for this endpoint, OAuth/SSO authentication is not enabled for this endpoint (identities).
401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks endpoints:write, or the plan doesn't include the rbac entitlement ("RBAC is not available on your current plan").
404 Not Found
Endpoint doesn't exist or doesn't belong to the calling account.
409 Conflict
Identifier collision (email, username, or OAuth identity already exists on this endpoint).
500
bcrypt or database error.
Request — password client
curl -X POST "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/rbac/clients" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{ "identifier": "alice@example.com", "display_name": "Alice", "email": "alice@example.com", "username": "alice", "password": "S3cr3tP@ss!", "metadata": {"team": "platform"} }'
Request — auto-generated token
curl -X POST "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/rbac/clients" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{"identifier": "service-bot", "auto_generate_token": true}'
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") created = client.endpoint_rbac.create_client("019bb1e4-e785-77d2-9966-c3cff31d0a0e", { "identifier": "service-bot", "auto_generate_token": True, }) print("Token (save now):", created["generated_token"])
Response — token client
{ "uuid": "019b4b9d-d300-736b-8601-153b3d9f70ee", "identifier": "service-bot", "status": "active", "has_password": false, "has_token": true, "has_oauth": false, "registration_source": "admin", "created_at": "2026-04-29T11:00:00Z", "updated_at": "2026-04-29T11:00:00Z", "generated_token": "et_7c1e9a4f2b6d8e0a3c5f7b9d1e3a5c7f9b2d4e6a8c0e2f4a6b8d0c2e4f6a8b0c" }
Was this helpful?
On this page
Create RBAC Client
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard