> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash cURL theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
octop admin rotate-jwt-secret
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.