Authentication API — Login, register, and password reset

The Authentication API handles every step of the account lifecycle — from creating a new account and verifying an email address to signing in and recovering a forgotten password. All endpoints are public (no token required) and are protected by a shared rate limiter to prevent brute-force and spam. After a successful login or email verification, you receive a signed JWT that you must include in every authenticated request.

All authentication endpoints enforce a rate limit of 10 requests per 15-minute window per IP. Exceeding this limit returns HTTP 429.

Rate limiting

Every authentication route shares the same rate-limit policy:

Property	Value
Window	15 minutes
Max requests	10 per IP
HTTP status on exceeded	`429 Too Many Requests`

{
  "message": "Demasiados intentos. Por favor, inténtalo de nuevo en 15 minutos."
}

Using the JWT token

After a successful login (POST /login) or email verification (GET /verify-email/:token), the API returns a signed JWT. Include it in the Authorization header for every authenticated request:

Authorization: Bearer <your-jwt-token>

The token payload contains:

Claim	Description
`id`	User’s numeric ID
`username`	User’s username
`role`	`user`, `referee`, or `admin`

Token expiry depends on the user’s role:

user — 7 days
admin / referee — 6 hours

Endpoints protected by the verifyToken middleware return 401 if the token is missing, invalid, or expired. The auth endpoints documented on this page are all public — no token is needed to call them.

POST /register

Creates a new user account and sends a verification email. The account cannot be used to log in until the email address is verified.

After registration, a verification link is emailed to the provided address. The account is automatically deleted if it is not verified within 24 hours.

Request body

username

string

required

Unique display name for the account. Checked case-insensitively and accent-insensitively.

string

required

Email address for the account. Checked case-insensitively. A verification email will be sent here.

password

string

required

Plain-text password. Stored as a bcrypt hash (10 rounds) — never stored in plain text.

Responses

message

string

Human-readable confirmation that registration succeeded and a verification email has been sent.

user

object

The newly created user record.

Show properties

number

Unique numeric ID assigned to the user.

username

string

The username supplied during registration.

string

The email address supplied during registration.

role

string

Always "user" for newly registered accounts.

Example request

curl --request POST \
  --url https://api.example.com/register \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "jdoe",
    "email": "[email protected]",
    "password": "S3cur3P@ss!"
  }'

Example response — 201 Created

{
  "message": "Registro exitoso. Por favor, revisa tu correo para verificar tu cuenta.",
  "user": {
    "id": 42,
    "username": "jdoe",
    "email": "[email protected]",
    "role": "user"
  }
}

Error responses

Status	Condition	Response body
`400`	One or more required fields are missing	`{ "message": "Username, email and password required" }`
`409`	Username already taken	`{ "message": "Username already exists" }`
`409`	Email already registered	`{ "message": "Email already exists" }`
`500`	Unexpected server error	`{ "message": "Error registering user" }`

Authenticates a user and returns a signed JWT. The username field accepts either a username or an email address.

Accounts that have not verified their email address cannot log in. The response includes "not_verified": true so the client can prompt the user to check their inbox or request a new verification email.

Request body

username

string

required

The account’s username or email address. Lookup is case-insensitive and accent-insensitive.

password

string

required

The account’s password in plain text.

Responses

token

string

A signed JWT. Include this value in the Authorization: Bearer <token> header for authenticated requests.

Example request

curl --request POST \
  --url https://api.example.com/login \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "jdoe",
    "password": "S3cur3P@ss!"
  }'

Example response — 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInVzZXJuYW1lIjoiamRvZSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzE2MDAwMDAwLCJleHAiOjE3MTY2MDQ4MDB9.SIGNATURE"
}

Error responses

Status	Condition	Response body
`400`	`username` or `password` field missing	`{ "message": "Username and password required" }`
`401`	No account found, or wrong password	`{ "message": "Invalid username or password" }`
`403`	Account has been deactivated by an administrator	`{ "message": "Esta cuenta ha sido desactivada." }`
`403`	Email address not yet verified	`{ "message": "Por favor, revisa tu bandeja de entrada y verifica tu correo electrónico antes de iniciar sesión.", "not_verified": true }`
`500`	Token generation or server error	`{ "message": "Error logging in" }`

GET /verify-email/:token

Verifies a user’s email address using the one-time token sent during registration (or after a resend request). On success, the account is activated and a valid JWT is returned so the client can log the user in automatically.

The verification token is a single-use, 64-character hex string generated server-side. It is invalidated immediately after a successful verification.

Path parameters

token

string

required

The verification token included in the email link. This is the value of the token query parameter from the link sent to the user’s inbox.

Responses

message

string

Confirmation that the account has been verified.

token

string

A valid JWT for the now-verified user. Use this to authenticate immediately without requiring a separate login step. Expiry follows the same role-based rules as /login.

Example request

curl --request GET \
  --url https://api.example.com/verify-email/a3f1c2e4d5b67890abcdef1234567890abcdef1234567890abcdef1234567890

Example response — 200 OK

{
  "message": "Cuenta verificada correctamente. Iniciando sesión...",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInVzZXJuYW1lIjoiamRvZSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzE2MDAwMDAwLCJleHAiOjE3MTY2MDQ4MDB9.SIGNATURE"
}

Error responses

Status	Condition	Response body
`400`	Token not found or account already verified	`{ "message": "Token de verificación inválido o la cuenta ya ha sido verificada." }`
`500`	Server error during verification or JWT generation	`{ "message": "Error en el servidor al verificar cuenta" }`

POST /resend-verification

Sends a new verification email to an unverified account. At least one of email or username must be provided.

Request body

string

The email address associated with the account. At least one of email or username is required.

username

string

The username associated with the account. At least one of email or username is required.

Responses

message

string

Confirmation that the verification email has been resent.

Example request

curl --request POST \
  --url https://api.example.com/resend-verification \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]"
  }'

Example response — 200 OK

{
  "message": "Se ha reenviado el correo de verificación. Por favor, revisa tu bandeja de entrada."
}

Error responses

Status	Condition	Response body
`400`	Neither `email` nor `username` provided	`{ "message": "El email o usuario es requerido" }`
`400`	Account is already verified	`{ "message": "Esta cuenta ya ha sido verificada." }`
`404`	No account matched the provided email or username	`{ "message": "No existe ninguna cuenta asociada." }`
`500`	Failed to send email or server error	`{ "message": "Error al enviar el correo. Inténtalo más tarde." }`

POST /forgot-password

Initiates the password-reset flow by emailing a reset link to the provided address. The reset link is valid for 15 minutes.

This endpoint always returns the same success message regardless of whether the email address is registered. This is intentional — it prevents account enumeration by an attacker.

Request body

string

required

The email address associated with the account that needs a password reset.

Responses

message

string

Always "Si el correo está registrado, recibirás un enlace de recuperación.", whether or not the email exists in the system.

Example request

curl --request POST \
  --url https://api.example.com/forgot-password \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]"
  }'

Example response — 200 OK

{
  "message": "Si el correo está registrado, recibirás un enlace de recuperación."
}

Error responses

Status	Condition	Response body
`400`	`email` field missing	`{ "message": "El email es requerido" }`
`500`	Failed to send email or server error	`{ "message": "Error en el servidor al procesar la solicitud" }`

POST /reset-password

Completes the password-reset flow by setting a new password using the token from the reset email.

Reset tokens expire 15 minutes after they are issued. Submitting an expired or already-used token returns 400.

Request body

token

string

required

The password-reset token included in the reset link sent by /forgot-password. This is a 64-character hex string.

newPassword

string

required

The new plain-text password. It will be hashed with bcrypt before being stored.

Responses

message

string

Confirmation that the password was updated successfully.

Example request

curl --request POST \
  --url https://api.example.com/reset-password \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "a3f1c2e4d5b67890abcdef1234567890abcdef1234567890abcdef1234567890",
    "newPassword": "N3wS3cur3P@ss!"
  }'

Example response — 200 OK

{
  "message": "Contraseña actualizada correctamente."
}

Error responses

Status	Condition	Response body
`400`	`token` or `newPassword` field missing	`{ "message": "Token y nueva contraseña requeridos" }`
`400`	Token not found or has expired	`{ "message": "El token es inválido o ha caducado." }`
`500`	Server error during password update	`{ "message": "Error en el servidor al restablecer contraseña" }`

Authentication

League Data

Administration

Documentation Index

​Rate limiting

​Using the JWT token

​POST /register

​Request body

​Responses

​Example request

​Example response — 201 Created

​Error responses

​POST /login

​Request body

​Responses

​Example request

​Example response — 200 OK

​Error responses

​GET /verify-email/:token

​Path parameters

​Responses

​Example request

​Example response — 200 OK

​Error responses

​POST /resend-verification

​Request body

​Responses

​Example request

​Example response — 200 OK

​Error responses

​POST /forgot-password

​Request body

​Responses

​Example request

​Example response — 200 OK

​Error responses

​POST /reset-password

​Request body

​Responses

​Example request

​Example response — 200 OK

​Error responses

Build docs developers (and LLMs) love

Rate limiting

Using the JWT token

POST /register

Request body

Responses

Example request

Example response — 201 Created

Error responses

POST /login

Request body

Responses

Example request

Example response — 200 OK

Error responses

GET /verify-email/:token

Path parameters

Responses

Example request

Example response — 200 OK

Error responses

POST /resend-verification

Request body

Responses

Example request

Example response — 200 OK

Error responses

POST /forgot-password

Request body

Responses

Example request

Example response — 200 OK

Error responses

POST /reset-password

Request body

Responses

Example request

Example response — 200 OK

Error responses