Octop Users and Admin API: Manage Accounts and Settings

Create users, assign module permissions, send invites, reset passwords, and read audit data.

Manage team accounts, invitations, and admin settings. You need permission to manage users (administrators have it).

Settings-page access is separate from chat: a new account can already talk to agents, but cannot change channels, connectors, or knowledge bases until you grant those in Management → Users. The web UI invite form can pre-check those boxes; creating a user through the API does not.

​

User management endpoints

Method	Path	Auth	Description
GET	/users/permissions	logged-in	Localized permission catalog
GET	/users	users	List all users
POST	/users	users	Create a user
GET	/users/{id}	users	Get user details
PATCH	/users/{id}	users	Update role, display name, email, enabled flag, or permissions
POST	/users/{id}/reset-password	users	Reset a user’s password
POST	/users/{id}/unlock-login	users	Clear login lockout
DELETE	/users/{id}	users	Delete a user
GET	/users/invites	users	List invites
POST	/users/invites	users	Create an invite
POST	/users/invites/{invite_id}/revoke	users	Revoke a pending invite

Non-admins can only grant access they already have. You cannot demote yourself or remove your last user-management access if nobody else can manage users.

​

Invite a teammate

In the web UI, open Management → Users and click Invite user. Share the link; it expires in 7 days by default (you can choose 1–90). After someone redeems it, they get a regular user account and a default assistant.

You can also create and revoke invites with the endpoints above.

​

Create a user

cURL

curl -X POST http://127.0.0.1:8088/api/users \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "alice",
    "password": "secure123",
    "role": "user",
    "display_name": "Alice Smith",
    "workspace_root_dir": "/data/alice",
    "token_quota": 1000000
  }'

A successful request returns 201 Created with the new user row. The role field accepts "user" or "admin". Optional workspace_root_dir limits where that user’s agents may write. Optional token_quota caps token usage for the account (the policy applies as soon as the user is created).

​

Update a user

Send a PATCH request with any subset of role, display_name, enabled, or locale. To disable an account without deleting it, set "enabled": false.

cURL

curl -X PATCH http://127.0.0.1:8088/api/users/alice \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"role": "admin", "display_name": "Alice Smith (Admin)"}'

​

Reset a password

Send a POST request with the new password. The user must change this password on next login if your policy requires it.

cURL

curl -X POST http://127.0.0.1:8088/api/users/alice/reset-password \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"new_password": "NewSecurePass!"}'

Returns 204 No Content on success.

​

Unlock a locked-out user

When a user exceeds the maximum number of failed login attempts (configured by OCTOP_LOGIN_MAX_ATTEMPTS), their account is locked until the lockout period expires or an admin clears it. Use POST /users/{id}/unlock-login to immediately restore access without waiting for the timeout.

cURL

curl -X POST http://127.0.0.1:8088/api/users/alice/unlock-login \
  -H 'Authorization: Bearer $TOKEN'

​

Admin overview and audit log

These endpoints give you a high-level view of instance activity.

Method	Path	Auth	Description
GET	/admin/overview	admin	User count, agent count, and runtime states
GET	/admin/audit-log	admin	Recent audit log entries

​

Overview

cURL

curl http://127.0.0.1:8088/api/admin/overview \
  -H 'Authorization: Bearer $TOKEN'

Returns {user_count, agent_count, ...} — useful for health dashboards and monitoring scripts.

​

Audit log

cURL

curl http://127.0.0.1:8088/api/admin/audit-log \
  -H 'Authorization: Bearer $TOKEN'

Returns recent audit rows recording key admin and user actions across the instance.

​

Rotate the JWT secret

Running octop admin rotate-jwt-secret immediately invalidates all active sessions across every user account — including your own. Every user will be logged out and must re-authenticate. Only rotate the JWT secret in a planned maintenance window or after a suspected credential compromise.

JWT secret rotation is performed via the Octop CLI, not the REST API:

octop admin rotate-jwt-secret

The new secret is generated server-side. After rotation, all users must re-login to obtain a new token.