Documentation | API Reference

Overview

The API uses JWT (JSON Web Token) for authentication. You need to obtain a token by logging in, then include it in the Authorization header for all protected requests.

How JWT Authentication Works

Follow these steps to authenticate and make API requests:

1

Send login request

POST your email and password to the login endpoint:

POST /api/v1/auth/login
Content-Type: application/json

{
    "email": "[email protected]",
    "password": "YourPassword123"
}

2

Receive JWT token

On successful login, you will receive a JWT token in the response:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

3

Use token in requests

Include the token in the Authorization header with Bearer prefix:

GET /api/v1/user/profile
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Registration

Registration is a two-step process. First, you request a verification code, then complete registration with the code.

1

Request verification code

Send name and email. A 6-digit verification code will be sent to the email.

POST /api/v1/auth/register
Content-Type: application/json

{
    "name": "John Doe",
    "email": "[email protected]",
    "locale": "en"  // optional, from /api/v1/languages
}

Response:

{
    "success": true,
    "message": "Verification code sent to email"
}

2

Complete registration

Send the verification code along with password and other details to create the account.

POST /api/v1/auth/register/verify
Content-Type: application/json

{
    "email": "[email protected]",
    "code": "123456",
    "password": "SecurePass123!",
    "country_code": "UA",  // from /api/v1/countries
    "phone": "+380501234567",  // optional
    "locale": "uk"  // optional, from /api/v1/languages
}

Response:

{
    "success": true,
    "message": "User registered successfully",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "[email protected]"
    }
}

Step 1 request fields

Field	Type	Required	Description
`name`	string	Yes	Full name (2-255 characters)
`email`	string	Yes	Valid email address
`locale`	string	No	Language for email (from /api/languages)

Step 2 request fields

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`code`	string	Yes	6-digit verification code from email
`password`	string	Yes	Min 8 chars, uppercase, lowercase, number
`country_code`	string	Yes	Country code (from /api/countries)
`phone`	string	No	International format (+380...)
`locale`	string	No	Preferred language (from /api/languages)

Verification code expires in: 10 minutes

Token Lifetime

JWT tokens have a limited lifetime. When your token expires, you will receive a 401 error and need to log in again.

Token expires after: 1 hour

Get Current User

To verify your token and get information about the current user:

GET /api/v1/auth/me
Authorization: Bearer YOUR_TOKEN

Response:

{
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+380501234567",
    "locale": "en",
    "country": {
        "code": "UA",
        "phone_code": "+380"
    },
    "roles": ["ROLE_USER"],
    "is_active": true,
    "created_at": "2026-01-03T10:00:00+00:00"
}