> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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

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

## Sign-in methods

Under **Management → Users** you get separate tabs: **User management**, **User groups**, **Role management**, **Feishu**, **WeCom**, **DingTalk**, **OIDC**, and **LDAP**.


![Users and LDAP](/images/en/ui-ldap.png "Users → LDAP")

- **Roles** — save permission templates (including finer personalization grants such as skills, tools, plugins, persona, and memory) and apply them when inviting people.
- **User groups** — limit who can use a skill package, knowledge base, connector, model, storage backend, or expert. On the resource, set **Who can use this** to **Specific user groups**. Administrators still pass.
- **LDAP** — directory login on the existing username/password form. With automatic provisioning off, create a **Directory account** here first. See [Authentication](/en/api/authentication.md#ldap-directory-login).
- **OIDC / Feishu / DingTalk / WeCom** — OAuth SSO. The `sso` permission is required to read or write provider settings. See [Authentication](/en/api/authentication.md) for `/auth/oauth/*` and `/auth/oidc/*`.

## Create a user


```bash 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`.


```bash 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.


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


> **NOTE**
> 
> 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.
> 



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


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


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


> **WARNING**
> 
> 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:

```bash
octop admin rotate-jwt-secret
```

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