Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abdelhafid37/talkbox/llms.txt

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

The auth endpoints are the entry point to the TalkBox API. Use POST /api/auth/register to create a new account and POST /api/auth/login to authenticate and receive the JWT that every other endpoint requires. Neither endpoint needs an Authorization header.

​
POST /api/auth/register

Creates a new user account. The server validates the supplied fields, checks for duplicate usernames and emails, bcrypt-hashes the password with 10 salt rounds, and stores the user in MongoDB. Does not require authentication.

​
Request body

​
username
string
required
A unique display name for the account. Must be between 3 and 30 characters after trimming leading and trailing whitespace.
​
email
string
required
The user’s email address. Must match the pattern [a-zA-Z0-9.]{2,}@[a-zA-Z]{2,}.[a-zA-Z]{2,}. Whitespace is trimmed before validation.
​
password
string
required
The account password. Must be at least 8 characters long. Stored as a bcrypt hash — never in plain text.

​
Success response — 201 Created

{ "message": "User registered successfully." }

​
Error responses

StatusCondition
400 Bad RequestAny required field is missing, not a string, empty after trimming, or fails length/format validation
409 ConflictThe username or email is already associated with an existing account
500 Internal Server ErrorAn unexpected database or server error occurred

​
Example

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "email": "alice@example.com",
    "password": "supersecret123"
  }'

{ "message": "User registered successfully." }

​
POST /api/auth/login

Authenticates an existing user by email and password. On success the server returns a signed JWT that encodes the user’s MongoDB _id as userId in the payload. Does not require authentication.

​
Request body

​
email
string
required
The email address registered to the account. Whitespace is trimmed before the database lookup.
​
password
string
required
The plain-text password. Compared against the stored bcrypt hash using bcrypt.compare.

​
Success response — 200 OK

{ "token": "<jwt>" }
The token is a signed JWT with the following payload: 
{ "userId": "64f1a2b3c4d5e6f7a8b9c0d1", "iat": 1700000000, "exp": 1700604800 }
Token lifetime is 7 days from the moment of issue.

​
Error responses

StatusCondition
400 Bad RequestEither email or password is missing or not a string
401 UnauthorizedNo user found for the given email, or the password does not match
500 Internal Server ErrorAn unexpected server error occurred

​
Example

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "supersecret123"
  }'

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2NGYxYTJiM2M0ZDVlNmY3YThiOWMwZDEiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDYwNDgwMH0.SIGNATURE" }
Store the returned token securely (e.g. in localStorage or an in-memory variable) and include it as Authorization: Bearer <token> on every request to a protected endpoint. The token expires after 7 days, at which point you must log in again to obtain a new one.

Build docs developers (and LLMs) love

Get started for freeTalk to us