Users & identity API

Application boundary#

These paths belong to your YAADMIN installation. They are not callable product-website APIs. Authenticated mutations require a session-matched X-CSRF-Token unless the route is public. Handler-local error codes are not exhaustive downstream schemas.

Verified routes#

Find a route in this category

11 routes

GET/users

Users page.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: user=None
Headers: none beyond shared session/CSRF
Response structure: HTML users.html
Important errors: 404
Approval behavior: no standalone approval behavior in this handler. Snapshot redaction prevents full credential/body reconstruction.

Verified route registration · handler users_page. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/security/users

Create user.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserCreatePayload [username, display_name, source, is_active]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, user}
Important errors: 400, 409
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`username`	`str = Field(min_length=1, max_length=255)`
`display_name`	`str \| None = Field(default=None, max_length=255)`
`source`	`str = Field(default="local", min_length=1, max_length=80)`
`is_active`	`bool = True`

Verified route registration · handler api_create_user. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/security/users/{user_id}

Update user.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserUpdatePayload [display_name, source, is_active]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, user}
Important errors: 400, 409
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`display_name`	`str \| None = Field(default=None, max_length=255)`
`source`	`str \| None = Field(default=None, min_length=1, max_length=80)`
`is_active`	`bool \| None = None`

Verified route registration · handler api_update_user. Some definitions may be partially redacted; no missing fields are inferred.

DELETE/api/security/users/{user_id}

Delete user.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, deleted_user_id}
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_delete_user. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/security/users/{user_id}/ui-language

Set user ui language.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UiPreferencesPayload [language, personal_prompt]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, language}
Important errors: 400, 404
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`language`	`str = Field(min_length=2, max_length=8)`
`personal_prompt`	`str = Field(default="", max_length=4000)`

Verified route registration · handler api_set_user_ui_language. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/security/users/{user_id}/password

Set user password.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserPasswordPayload [password, must_change_password]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok}
Important errors: 400, 404, 409
Approval behavior: no standalone approval behavior in this handler. Snapshot redaction prevents full credential/body reconstruction.

Request fields

Field	Verified definition
`password`	`type/default redacted; field name verified`
`must_change_password`	`type/default redacted; field name verified`

Verified route registration · handler api_set_user_password. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/security/users/{user_id}/roles

Update user roles.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserRolesPayload [role_ids]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, roles}
Important errors: none literal; shared/helper errors apply
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`role_ids`	`list[str] = Field(default_factory=list, max_length=500)`

Verified route registration · handler api_update_user_roles. Some definitions may be partially redacted; no missing fields are inferred.

PUT/api/security/users/{user_id}/rag/profile

Update user rag profile.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserRAGProfilePayload [enabled, top_k, max_context_chars]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, profile}
Important errors: 400, 404, 503
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`enabled`	`bool = False`
`top_k`	`int = Field(default=6, ge=1, le=12)`
`max_context_chars`	`int = Field(default=6000, ge=1000, le=20000)`

Verified route registration · handler api_update_user_rag_profile. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/security/users/{user_id}/rag/documents

Add user rag document.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserRAGDocumentPayload [title, content, source_type]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, document}
Important errors: 400, 404, 503
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`title`	`str = Field(min_length=1, max_length=255)`
`content`	`str = Field(min_length=1, max_length=250000)`
`source_type`	`str = Field(default="note", min_length=1, max_length=64)`

Verified route registration · handler api_add_user_rag_document. Some definitions may be partially redacted; no missing fields are inferred.

DELETE/api/security/users/{user_id}/rag/documents/{document_id}

Delete user rag document.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: none
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, deleted, document_id}
Important errors: 404, 503
Approval behavior: no standalone approval behavior in this handler.

Verified route registration · handler api_delete_user_rag_document. Some definitions may be partially redacted; no missing fields are inferred.

POST/api/security/users/{user_id}/rag/test

Test user rag.

Authentication: session + administrator role
Permission: no separate permission identifier in handler (admin/owner/runtime checks as above)
Request body: UserRAGTestPayload [query]
Query parameters: none explicitly read
Headers: none beyond shared session/CSRF
Response structure: {ok, retrieval}
Important errors: 400, 404, 503
Approval behavior: no standalone approval behavior in this handler.

Request fields

Field	Verified definition
`query`	`str = Field(min_length=1, max_length=20000)`

Verified route registration · handler api_test_user_rag. Some definitions may be partially redacted; no missing fields are inferred.

Implementation reference: 2026-10-02. Labels distinguish verified behavior, partial implementation and architectural intent.