Skip to main content
The Users API provides endpoints for managing user accounts, including retrieving user information, updating plugins, handling email verification, accepting terms of service, and deleting accounts.

​
Authentication

All endpoints (except email verification endpoints) require JWT authentication via the Authorization header: 
Authorization: Bearer <your_jwt_token>

​
Get User Information

curl -X GET "https://your-domain.com/api/user" \
  -H "Authorization: Bearer <token>"
Retrieve the authenticated user’s information.

​
Response

​
id
string
User ID
​
username
string
Username
​
email
string
Email address
​
name
string
Display name
​
avatar
string
Avatar URL (S3 URLs are automatically refreshed if expired)
​
role
string
User role (e.g., “USER”, “ADMIN”)
​
provider
string
Authentication provider (“local”, “google”, “github”, etc.)
​
emailVerified
boolean
Whether email is verified
​
plugins
array
Array of installed plugin identifiers
​
createdAt
string
ISO 8601 timestamp
Note: Sensitive fields (password, totpSecret, backupCodes) are always excluded from the response.

​
Get Terms of Service Status

curl -X GET "https://your-domain.com/api/user/terms" \
  -H "Authorization: Bearer <token>"
Check whether the user has accepted the terms of service.

​
Response

​
termsAccepted
boolean
Whether the user has accepted terms

​
Error Responses

  • 404 Not Found: User not found
  • 500 Internal Server Error: Failed to fetch status

​
Accept Terms of Service

curl -X POST "https://your-domain.com/api/user/terms/accept" \
  -H "Authorization: Bearer <token>"
Mark the terms of service as accepted for the authenticated user.

​
Response

​
message
string
Success message: “Terms accepted successfully”

​
Error Responses

  • 404 Not Found: User not found
  • 500 Internal Server Error: Failed to accept terms

​
Update User Plugins

curl -X POST "https://your-domain.com/api/user/plugins" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pluginKey": "web_search",
    "action": "install",
    "auth": {
      "TAVILY_API_KEY": "your-api-key"
    },
    "isEntityTool": false
  }'
Install or uninstall plugins and manage plugin authentication credentials.

​
Request Body

​
pluginKey
string
required
Plugin identifier (e.g., “web_search”, “mcp_serverName”)
​
action
string
required
Action to perform: “install” or “uninstall”
​
auth
object
Authentication credentials (key-value pairs)
​
isEntityTool
boolean
default:"false"
Whether this is an entity-level tool (doesn’t update user.plugins array)

​
Plugin-Specific Behavior

​
Web Search Plugin

When installing/uninstalling web_search, all web search provider keys are managed:
  • Tavily, Google Search, Brave Search, SerpAPI, etc.

​
MCP Servers

For MCP tools (starting with mcp_):
  • Install: Saves provided credentials
  • Uninstall: Deletes all credentials for the MCP server and disconnects active sessions
  • OAuth MCP Servers: Automatically revokes OAuth tokens on uninstall

​
Response

Returns 200 OK on success. Error responses include status code and message.

​
Error Responses

  • 400 Bad Request: Invalid parameters
  • 500 Internal Server Error: Plugin update failed

​
Verify Email

curl -X POST "https://your-domain.com/api/user/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<verification_token>"
  }'
Verify a user’s email address using a verification token sent via email. No authentication required.

​
Request Body

​
token
string
required
Email verification token from the verification link

​
Response

Returns verification result.

​
Error Responses

  • 400 Bad Request: Invalid or expired token
  • 500 Internal Server Error: Verification failed

​
Resend Verification Email

curl -X POST "https://your-domain.com/api/user/verify/resend" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
Resend the email verification link. Rate limited.

​
Request Body

​
email
string
required
Email address to send verification to

​
Response

Returns success message.

​
Error Responses

  • 400 Bad Request: Invalid email or already verified
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Failed to send email

​
Delete User Account

curl -X DELETE "https://your-domain.com/api/user/delete" \
  -H "Authorization: Bearer <token>"
Permanently delete the authenticated user’s account and all associated data. Requires account deletion to be enabled in server configuration.

​
What Gets Deleted

The following data is permanently removed:
  • All messages and conversations
  • All user sessions
  • All presets and settings
  • All files (including cloud storage)
  • All tool calls and memory entries
  • All agents and assistants
  • All API keys and tokens
  • All conversation tags
  • All user prompts and actions
  • User profile and authentication data
  • ACL entries and group memberships

​
Response

​
message
string
Success message: “User deleted”

​
Error Responses

  • 403 Forbidden: Account deletion is disabled in server configuration
  • 500 Internal Server Error: Deletion failed

​
User Settings

User-specific settings are managed through a separate sub-route. See the settings endpoint at /api/user/settings for managing user preferences and configuration.

​
Plugin Management

​
Available Plugins

Common plugins that can be managed:
Plugin KeyDescriptionRequired Auth
web_searchWeb search capabilityProvider API keys (Tavily, Google, etc.)
code_interpreterExecute codeMay require API key depending on provider
dall-eImage generationOpenAI API key
mcp_<serverName>MCP server toolsServer-specific credentials

​
Plugin Auth Flow

  1. Install Plugin:
    • Frontend calls POST /api/user/plugins with action: "install" and credentials
    • Server validates and stores credentials securely
    • Plugin is added to user’s installed plugins list
  2. Update Credentials:
    • Call POST /api/user/plugins with action: "install" and new credentials
    • Existing credentials are updated
  3. Uninstall Plugin:
    • Call POST /api/user/plugins with action: "uninstall" and auth: {}
    • Credentials are deleted
    • Plugin is removed from user’s list
    • For MCP servers, active connections are disconnected

​
MCP OAuth Cleanup

When uninstalling OAuth-enabled MCP servers:
  1. Access and refresh tokens are revoked at the OAuth provider
  2. Tokens are deleted from the database
  3. OAuth flow state is cleared from cache
  4. Active server connections are terminated

​
Common Error Codes

Status CodeDescription
400Bad Request - Invalid parameters or malformed request
401Unauthorized - Invalid or missing JWT token
403Forbidden - Operation not allowed (e.g., account deletion disabled)
404Not Found - User not found
429Too Many Requests - Rate limit exceeded (verification emails)
500Internal Server Error - Server-side error occurred

Build docs developers (and LLMs) love

Get started for freeTalk to us