Skip to main content
The Elemental Battlecards API provides authentication endpoints for user registration and login using JWT tokens. All authentication routes are prefixed with /api/auth.
Authentication endpoints are only available when DB_ENABLED=true is set in the environment configuration. In LAN mode, these routes are disabled.

​
Register User

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player1",
    "email": "[email protected]",
    "password": "securepassword123"
  }'
Registers a new user account. Passwords are hashed using bcrypt with a salt factor of 10 before storage.

​
Request Body

​
username
string
required
The username for the new account. Must be unique.
​
email
string
required
The email address for the new account. Must be unique and not already registered.
​
password
string
required
The password for the new account. Will be hashed before storage.

​
Response

​
message
string
Success or error message describing the result of the registration attempt.
{
  "message": "Usuario registrado exitosamente."
}

​
Login User

curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player1",
    "password": "securepassword123"
  }'
Authenticates a user and returns a JWT token valid for 1 hour. The token should be included in subsequent requests that require authentication.

​
Request Body

​
username
string
required
The username of the account to log in.
​
password
string
required
The password for the account.

​
Response

​
token
string
JWT authentication token valid for 1 hour. Contains user ID and username in the payload.
​
message
string
Error message if authentication fails.
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
JWT Token Payload

The JWT token contains the following payload structure: 
{
  user: {
    id: user.id,
    username: user.username
  }
}
Tokens expire after 1 hour. Clients should handle token expiration and prompt users to re-authenticate.

​
Health Check

curl http://localhost:3001/ping
Simple health check endpoint to verify the API server is running and responding to requests.

​
Response

​
ok
boolean
Always returns true when the server is operational.
​
time
number
Current server timestamp in milliseconds (Unix epoch).
​
host
string
The hostname from the request.
{
  "ok": true,
  "time": 1709539200000,
  "host": "localhost"
}
The /ping endpoint does not require authentication and is always available regardless of database configuration.

​
Security Notes

  • Passwords are hashed using bcrypt with a salt factor of 10
  • JWT tokens use the JWT_SECRET environment variable for signing
  • Ensure JWT_SECRET is set to a strong, random value in production
  • Database SSL is configurable via DB_REQUIRE_SSL environment variable

​
Implementation Reference

Authentication logic is implemented in:
  • Routes: Backend/routes/authRoutes.js:7-13
  • Controller: Backend/controllers/authController.js
  • Server configuration: Backend/server.js:38-49

Build docs developers (and LLMs) love

Get started for freeTalk to us