---
title: "Manage Speak AI account users with the admin endpoints"
description: "Create users in your Speak AI account, update an existing user, and list every user the account contains. These endpoints are for account admins."
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Speak AI account users with the admin endpoints
import EndpointIndex from "@/components/api/EndpointIndex.astro";
The Speak AI API exposes 3 admin endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).
Manage your team.
## What can you do with the admin endpoints?
Speak AI groups these 3 endpoints under the admin resource. Each entry below links to the full reference for that endpoint further down this page.
| Method | Path | What it does |
| --- | --- | --- |
| `POST` | [`/admin/user`](#post-admin-user) | Create New User |
| `PUT` | [`/admin/user`](#put-admin-user) | Update User |
| `GET` | [`/admin/users`](#get-admin-users) | List users |
Create New User
#### Add User Endpoint
This endpoint allows administrators to add a new user to the system. The request requires a JSON payload containing user details.
##### Request Parameters
The request body should be in JSON format and include the following parameters:
- `firstName` (string): The first name of the user.
- `lastName` (string): The last name of the user.
- `email` (string): The email address of the user.
- `isActive` (boolean): Indicates whether the user account is active.
- `isVerified` (boolean): Indicates whether the user's email has been verified.
- `permission` (object): An object specifying the permissions granted to the user:
- `audio` (boolean): Permission to access audio features.
- `video` (boolean): Permission to access video features.
- `text` (boolean): Permission to access text features.
- `addPayment` (boolean): Permission to manage payment options.
- `userManagement` (boolean): Permission to manage other users.
##### Expected Response
Upon a successful request, the server will respond with a confirmation of the user creation, typically including the user ID and any other relevant details about the newly created user.
##### Notes
- Ensure that the email provided is unique and valid to avoid conflicts.
- Permissions should be assigned based on the user's role within the organization.
- This endpoint is restricted to users with administrative privileges.
### Request body
Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.
| Field | Type | Description |
| --- | --- | --- |
| `_id` | string | Pass an existing user id. Leave it out when you are creating a new team member. Optional. Empty string is accepted. The create controller never reads it, so it has no effect on this endpoint. |
| `email` | string, **required** | Give the email address to invite. This is the only property the server always requires. Required. Must be a valid email address. Lowercased and trimmed. An empty string is rejected. |
| `firstName` | string | Give the new member's first name. Optional. Trimmed. No minimum or maximum length. |
| `lastName` | string | Give the new member's last name. Optional. Trimmed. No minimum or maximum length. |
| `isActive` | boolean | Accepted for compatibility. The create endpoint ignores it, and the new account is created through the invite flow. Optional. The declared default is true, but the middleware discards the converted value, and the create controller never reads this key. |
| `isVerified` | boolean | Accepted for compatibility. The create endpoint ignores it. Optional. The declared default is false, and the same caveat about discarded conversions applies. The create controller never reads this key. |
| `permission` | object | Set what the new member can do. Anything you leave out falls back to the defaults for their role. Optional object with a fixed key set, defined. Unknown keys are rejected. Accepted keys: `role` (string, one of owner, admin, member); `folder` object with create, delete, download, share, assign, accessAll; `recorder` object with create, edit, delete, download, accessAll; `media` object with delete, edit, download, share; `payment` object with manageCards, manageInvoices; `teamManagement` object with manageMembers, manageGroups; `developer` object with accessKeys; `profileSettings` object with accountPreferences, accountCustomization, dataManagement; `meetingAssistant` object with customizeAssistant, shareMeetings, routeMeetings, excludeMeetings, globalSettings. Every leaf key is a boolean. The controller reads permission.role, falls back to member, and merges what you send over the role defaults. |
**`200` Success**
The spec records this status code with no example body.
Update User
#### Update User Details
This endpoint allows administrators to update the details of a user in the system. It is a PUT request that modifies the user's information based on the provided payload.
##### Request Parameters
The request body should be a JSON object with the following parameters:
- **_id** (string): The unique identifier of the user to be updated.
- **email** (string): The email address of the user. This field can be left empty if no change is required.
- **firstName** (string): The first name of the user.
- **lastName** (string): The last name of the user.
- **isActive** (boolean): Indicates whether the user account is active.
- **isVerified** (boolean): Indicates whether the user's email has been verified.
- **permission** (object): An object that defines the permissions for the user with the following keys:
- **audio** (boolean): Permission to access audio features.
- **video** (boolean): Permission to access video features.
- **text** (boolean): Permission to access text features.
- **addPayment** (boolean): Permission to add payment methods.
- **userManagement** (boolean): Permission to manage other users.
##### Expected Response
Upon a successful update, the API will return a response indicating the status of the operation. The response typically includes a success message and may also return the updated user details.
##### Notes
- Ensure that the user ID provided in the request is valid and corresponds to an existing user in the system.
- The permissions object allows for fine-grained control over what the user can access, so be sure to set these values according to your application's requirements.
- If any required fields are missing or invalid, the API will return an error response with details about the issue.
### Request body
Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.
| Field | Type | Description |
| --- | --- | --- |
| `_id` | string | Give the id of the user you are updating. The validator treats it as optional, but the update fails without it. Optional in the schema, and unlike the create schema it does not allow an empty string. The controller calls User.findById(_id) and returns 404 when nothing matches, so omitting it returns 404 rather than 400. |
| `email` | string, **required** | Give the user's email address. You have to send a valid one on every update, even though the update ignores it. Required. Must be a valid email address. Lowercased and trimmed. An empty string is rejected. The controller never reads this key, so you cannot use it to change the address. |
| `firstName` | string | Set the user's first name. Leave it out to keep the stored value. Optional. Trimmed. No minimum or maximum length. Omitted keys are stripped from the update, so they keep their stored values (keys you leave out are not written). |
| `lastName` | string | Set the user's last name. Leave it out to keep the stored value. Optional. Trimmed. No minimum or maximum length. Omitted keys are stripped from the update, so they keep their stored values. |
| `isActive` | boolean | Set whether the account stays active. Send false to deactivate the user, which also disconnects their calendars. Optional. The declared default is true, but the middleware discards the converted value, so no default is applied to the request and leaving it out keeps the current state. Sending false for a currently active user triggers a calendar disconnect. |
| `isVerified` | boolean | Accepted for compatibility. The update endpoint ignores it. Optional. The declared default is true, with the same discarded-conversion caveat. The update controller never reads this key. |
| `permission` | object | Set what the user can do. The validator treats this as optional, but the update fails without it. Same fixed key set as the create endpoint, defined. Unknown keys are rejected. Accepted keys: `role` (string, one of owner, admin, member); `folder` object with create, delete, download, share, assign, accessAll; `recorder` object with create, edit, delete, download, accessAll; `media` object with delete, edit, download, share; `payment` object with manageCards, manageInvoices; `teamManagement` object with manageMembers, manageGroups; `developer` object with accessKeys; `profileSettings` object with accountPreferences, accountCustomization, dataManagement; `meetingAssistant` object with customizeAssistant, shareMeetings, routeMeetings, excludeMeetings, globalSettings. Every leaf key is a boolean. The controller reads permission.role without a null check, and the resulting error is caught at:237-240, so omitting permission returns 500 rather than 400. Setting meetingAssistant.customizeAssistant to false also deletes the user's meeting assistant settings (:214-224). |
**`200` Success**
The spec records this status code with no example body.
List users
#### Get Users
This endpoint retrieves a list of users from the admin panel. It is primarily used by administrators to access user information stored in the system.
##### Request
- **Method**: GET
- **Endpoint**: `https://api.speakai.co/v1/admin/users`
##### Response
The response will contain a JSON object with the following structure:
- **users**: An array of user objects, where each user object includes:
- **id**: Unique identifier for the user.
- **name**: The name of the user.
- **email**: The email address of the user.
- **role**: The role assigned to the user (e.g., admin, user).
- **status**: The current status of the user (e.g., active, inactive).
##### Example Response
``` json
{
"users": [
{
"id": "123",
"name": "John Doe",
"email": "john.doe@example.com",
"role": "admin",
"status": "active"
},
{
"id": "124",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"role": "user",
"status": "inactive"
}
]
}
```
##### Notes
- Ensure that appropriate authentication and authorization headers are included in the request to access this endpoint.
- The response may vary based on the user's permissions and the number of users in the system.
**`200` Success**
The spec records this status code with no example body.
## Related pages
- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)
Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-admin).
Source: https://docs.speakai.co/api/admin/index.mdx