Admin

Replace a user's roles

Replaces the platform roles of any user. Needs the admin role, and each role that changes needs the caller to hold the role that grants it (today admin grants admin). Values outside the catalog are rejected with a 400, and a caller cannot remove their own admin role.

put/v1/admin/users/{user_id}/roles

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/admin/users/{user_id}/roles
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

user_idstring required

Request body

rolesstring[] required

The complete new list; an empty array clears every role.

Example request

{
  "roles": [
    "admin"
  ]
}

Response

The user with the new roles.

idstring required

Public user ID (user_ prefix).

emailstring email required
namestring nullable
email_verifiedboolean required
rolesstring[] required

Roles on naturali itself, not on a project. Empty for almost every account; admin marks a naturali operator. Changed only through PUT /v1/admin/users/{user_id}/roles, by a caller holding the role that grants each one.

usage_alertsboolean required

Whether the account is emailed when its model credit, runs or indexed storage reaches 75%, 90% and 100%. On for a new account.

created_atstring date-time required

Example response

{
  "id": "user_V1StGXR8Z5jdHi6B",
  "email": "ana@acme.com",
  "name": "Ana Silva",
  "email_verified": true,
  "roles": [],
  "usage_alerts": true,
  "created_at": "2026-07-17T00:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.