Skip to main content
POST
/
api
/
login
Login User
curl --request POST \
  --url https://api.example.com/api/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "json": "<string>"
}
'
{
  "sub": 123,
  "email": "<string>",
  "name": "<string>",
  "surname": "<string>",
  "description": "<string>",
  "image": "<string>",
  "iat": 123,
  "exp": 123
}

​
Overview

Authenticates a user with email and password, returning a JWT token for subsequent API requests. The endpoint supports two response formats: a token string or a decoded token object with user details.

​
Request

​
Body Parameters

The request body must contain a json parameter with a JSON string containing the login credentials.
​
json
string
required
JSON string containing the login credentials with the following fields:
​
email
string
required
User’s email address. Must be a valid email format.
​
password
string
required
User’s password. Will be hashed using SHA-256 for authentication.
​
gettoken
boolean
Optional parameter to control response format:
  • If omitted or false: Returns JWT token as a string
  • If true: Returns decoded token object with user details

​
Request Examples

cURL - Get Token String
curl -X POST https://your-domain.com/api/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'json={"email":"[email protected]","password":"secretpassword123"}'
cURL - Get User Object
curl -X POST https://your-domain.com/api/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'json={"email":"[email protected]","password":"secretpassword123","gettoken":true}'

​
Response

​
Success Response - Token String (200)

When gettoken is omitted or false, returns a JWT token string: 
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImVtYWlsIjoiam9obi5kb2VAZXhhbXBsZS5jb20iLCJuYW1lIjoiSm9obiIsInN1cm5hbWUiOiJEb2UiLCJkZXNjcmlwdGlvbiI6bnVsbCwiaW1hZ2UiOm51bGwsImlhdCI6MTcwOTU1MDYwMCwiZXhwIjoxNzEwMTU1NDAwfQ.signature"
Use this token in the Authorization header for authenticated requests to other API endpoints.

​
Success Response - User Object (200)

When gettoken is true, returns a decoded token object with user information:
​
sub
integer
User ID (subject identifier)
​
email
string
User’s email address
​
name
string
User’s first name
​
surname
string
User’s last name
​
description
string
User’s profile description (may be null)
​
image
string
User’s profile image filename (may be null)
​
iat
integer
Token issued at timestamp (Unix timestamp)
​
exp
integer
Token expiration timestamp (Unix timestamp). Valid for 7 days from issue.

​
User Object Example

{
  "sub": 1,
  "email": "[email protected]",
  "name": "John",
  "surname": "Doe",
  "description": null,
  "image": null,
  "iat": 1709550600,
  "exp": 1710155400
}

​
Error Responses

Returned when the input data fails validation.
{
  "status": "error",
  "code": "404",
  "message": "El usuario no se ha podido identificar",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ]
  },
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
Validation rules:
  • email: Must be present and a valid email format
  • password: Must be present
Returned when email or password is incorrect.
{
  "status": "error",
  "message": "Login incorrecto."
}
This error is returned when credentials don’t match any user in the database.

​
JWT Token Details

​
Token Structure

The JWT token contains the following claims:
  • sub: User ID
  • email: User’s email address
  • name: User’s first name
  • surname: User’s last name
  • description: User’s profile description
  • image: User’s profile image filename
  • iat: Token issued at timestamp
  • exp: Token expiration timestamp

​
Token Expiration

JWT tokens are valid for 7 days (604,800 seconds) from the time of issue. After expiration, users must login again to obtain a new token.

​
Token Usage

Include the JWT token in the Authorization header for authenticated API requests: 
Authorization: YOUR_JWT_TOKEN

​
Important Notes

Password Hashing: The password is hashed using SHA-256 before authentication. This matches the hashing algorithm used during registration.
Response Format: All login responses return HTTP status code 200, even for errors. Check the status field in the response body to determine success or failure.
JSON Parameter Format: Like the register endpoint, this requires a json parameter containing a JSON string, not direct JSON in the request body.
Token vs Object: Use gettoken: false (default) when you only need the token for API authentication. Use gettoken: true when you need immediate access to user details without making an additional API call.

Build docs developers (and LLMs) love

Get started for freeTalk to us