Octop Users and Admin API: Manage Accounts and Settings#

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

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.

#Single sign-on

Configure OpenID Connect, Feishu, DingTalk, and WeCom under Management → Users → Single sign-on. The sso permission is required to read or write provider settings. See Authentication for the /auth/oauth/* and /auth/oidc/* routes, including bind and unbind.

#Create a user

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 -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 -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

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.

#Overview

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 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

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.