Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HelenaLM32/ECHO/llms.txt

Use this file to discover all available pages before exploring further.

The users API covers the full account lifecycle: registering a new ECHO account, authenticating to receive a JWT token, reading and updating user data, and deleting accounts. Most endpoints that modify data require a valid Bearer token in the Authorization header. See Authenticate with the ECHO API for details on obtaining a token.
The base URL for all endpoints on a local development server is http://localhost:8084. Replace this with your deployed API URL in production.

​
Get all users

This endpoint is restricted to users with the ADMIN role. Requests from non-admin accounts will receive a 403 response.
GET /users
Returns a list of all registered users.

​
Authentication

Requires a valid JWT token with ADMIN role.

​
Example

curl -X GET http://localhost:8084/users \
  -H "Authorization: Bearer <token>"

​
Response fields

​
id
number
required
Unique identifier for the user.
​
email
string
required
The user’s email address.
​
username
string
required
The user’s display name.
​
roles
array
required
List of role names assigned to the user. Possible values: ADMIN, USER, CREATOR, VENUE_MANAGER.

​
Get user by ID

GET /users/{id}
Returns a single user record by their numeric ID.

​
Path parameters

​
id
number
required
The numeric ID of the user to retrieve.

​
Example

curl -X GET http://localhost:8084/users/42 \
  -H "Authorization: Bearer <token>"

​
Response fields

​
id
number
required
Unique identifier for the user.
​
email
string
required
The user’s email address.
​
username
string
required
The user’s display name.
​
roles
array
required
List of role names assigned to the user (e.g., ["USER"], ["ADMIN"]).

​
Error codes

StatusMeaning
404No user exists with the given ID.

​
Register new user

POST /users/register
Creates a new ECHO account. No authentication is required. After registration, call /users/login to obtain a JWT token.

​
Request body

​
email
string
required
A valid email address. Must be unique across all accounts.
​
username
string
required
A display name. Must be at least 3 characters long.
​
password
string
required
Account password. Validated server-side for minimum length and format.

​
Example

curl -X POST http://localhost:8084/users/register \
  -H "Content-Type: application/json" \
  -d '{"email":"artist@example.com","username":"myartist","password":"SecurePass123"}'

​
Response fields

​
id
number
required
The newly created user’s ID.
​
email
string
required
The registered email address.
​
username
string
required
The chosen display name.

​
Error codes

StatusMeaning
400Validation failed (malformed email, username too short, weak password).
409An account with the given email already exists.

​
Login

POST /users/login
Authenticates an existing account and returns a JWT token as a plain string in the response body.

​
Request body

​
email
string
required
The email address used to register the account.
​
password
string
required
The account password.

​
Example

curl -X POST http://localhost:8084/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"artist@example.com","password":"SecurePass123"}'

​
Response

On success, returns a JSON object containing the JWT token and user details. Store the token securely and include it as a Bearer token on subsequent authenticated requests. 
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "id": 42,
  "email": "artist@example.com",
  "username": "myartist",
  "roles": ["USER"],
  "isActive": true,
  "avatarUrl": null
}

​
Error codes

StatusMeaning
401Incorrect email or password.

​
Update user

PUT /users/{id}
Replaces the user record with the provided data. You must be authenticated as the user being updated, or hold the ADMIN role.

​
Path parameters

​
id
number
required
The numeric ID of the user to update.

​
Request body

​
email
string
Updated email address.
​
username
string
Updated display name.

​
Example

curl -X PUT http://localhost:8084/users/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","username":"newname"}'

​
Error codes

StatusMeaning
400Validation failed.
403Not authorized to update this user.
404No user exists with the given ID.

​
Delete user

DELETE /users/{id}
Permanently deletes a user account. You may delete your own account, or an ADMIN may delete any account.
This action is irreversible. Deleting a user account removes all associated data.

​
Path parameters

​
id
number
required
The numeric ID of the user to delete.

​
Example

curl -X DELETE http://localhost:8084/users/42 \
  -H "Authorization: Bearer <token>"

​
Error codes

StatusMeaning
403Not authorized to delete this user.
404No user exists with the given ID.

​
Update credentials

PATCH /users/{id}/credentials
Updates the username, password, or both for a user account. Changing the password requires the current password for verification. You must be authenticated as the account owner.

​
Path parameters

​
id
number
required
The numeric ID of the user whose credentials to update.

​
Request body

All fields are optional, but at least one must be provided.
​
username
string
New display name to set. Must be at least 3 characters.
​
currentPassword
string
The account’s current password. Required when setting a new password.
​
newPassword
string
The password to replace the current one. Requires currentPassword to also be provided.

​
Example

curl -X PATCH http://localhost:8084/users/42/credentials \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"OldPass123","newPassword":"NewPass456"}'

​
Error codes

StatusMeaning
400Validation failed or currentPassword is incorrect.
403Not authorized to update this user’s credentials.
404No user exists with the given ID.

Build docs developers (and LLMs) love

Get started for freeTalk to us