Authentication Guide for API Ecommerce JWT Endpoints

API Ecommerce uses stateless JWT authentication powered by tymon/jwt-auth. Every protected endpoint expects a signed bearer token; no session cookies or CSRF tokens are involved. The API enforces two distinct user roles via a type_user column on the users table: type_user=1 identifies admin accounts, while type_user=2 identifies customer accounts. Each role has a dedicated login endpoint — tokens are not interchangeable across roles, and attempting to use a customer token on an admin route (or vice versa) results in a 401 Unauthorized response.

Token format

All protected endpoints require the following HTTP header:

Authorization: Bearer <your_jwt_token>

Tokens are signed with the JWT_SECRET value in your .env file and expire after the TTL configured in config/jwt.php (default 60 minutes, reported as expires_in seconds in login responses). Each issued token is also persisted to the user_tokens table alongside the issuing IP address and User-Agent, enabling per-device session management.

Register

POST /api/auth/register Creates a new customer account (type_user=2). On success, a verification email is dispatched to the provided address. The account cannot be used to log in until email verification is completed. Returns HTTP 201 with the created user object.

Registration is rate-limited to 10 requests per minute per IP address. Exceeding this limit returns HTTP 429 Too Many Requests.

Request fields

name

string

required

The customer’s first name.

surname

string

required

The customer’s last name (surname).

phone

string

required

Contact phone number.

string

required

A unique, valid email address. Duplicate emails are rejected with HTTP 400.

password

string

required

Minimum 8 characters. Stored as a bcrypt hash.

Example

curl -s -X POST https://your-api.example.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane",
    "surname": "Doe",
    "phone": "3001234567",
    "email": "jane@example.com",
    "password": "secret123"
  }'

POST /api/auth/login Authenticates an admin account (type_user=1). Rejects credentials belonging to customer accounts, even if the email and password are valid.

/api/auth/login is exclusively for admin accounts (type_user=1). Submitting customer credentials returns HTTP 401 Unauthorized. Use /api/auth/login_ecommerce for customer logins.

Request fields

string

required

The admin account’s email address.

password

string

required

The admin account’s password.

Example

curl -s -X POST https://your-api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "adminpassword"}'

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "full_name": "Admin User",
    "email": "admin@example.com",
    "name": "Admin"
  }
}

access_token

string

The signed JWT. Pass this in the Authorization: Bearer header for all protected requests.

token_type

string

Always "bearer".

expires_in

integer

Token lifetime in seconds (default 3600). After expiry, call /api/auth/refresh to obtain a new token without re-entering credentials.

user.full_name

string

Concatenation of name and surname fields.

user.email

string

The authenticated user’s email address.

user.name

string

The authenticated user’s first name.

POST /api/auth/login_ecommerce Authenticates a customer account (type_user=2). In addition to validating credentials, this endpoint checks that email_verified_at is set on the account — unverified customers receive HTTP 401 even with correct credentials.

/api/auth/login_ecommerce is exclusively for customer accounts (type_user=2). Admin credentials are rejected. Customers must also complete email verification before their first login.

Request fields

string

required

The customer’s registered email address.

password

string

required

The customer’s password (minimum 8 characters at registration time).

Example

curl -s -X POST https://your-api.example.com/api/auth/login_ecommerce \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "password": "secret123"}'

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "full_name": "Jane Doe",
    "email": "jane@example.com",
    "name": "Jane"
  }
}

access_token

string

The signed JWT. Pass this in the Authorization: Bearer header for all protected storefront requests.

token_type

string

Always "bearer".

expires_in

integer

Token lifetime in seconds (default 3600).

user.full_name

string

Concatenation of the customer’s name and surname fields.

user.email

string

The authenticated customer’s email address.

user.name

string

The authenticated customer’s first name.

Token refresh

POST /api/auth/refresh Issues a new JWT without requiring the user to re-enter their credentials. The current token must still be valid (not expired and not invalidated) at the time of the request. Requires: Authorization: Bearer <current_token>

Example

curl -s -X POST https://your-api.example.com/api/auth/refresh \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

The response has the same shape as a login response: access_token, token_type, expires_in, and user.

Refresh tokens proactively before the expires_in window closes to avoid interrupting user sessions. Your client should store the new access_token returned by this endpoint and discard the old one.

Logout

POST /api/auth/logout Invalidates the currently authenticated token and removes its record from the user_tokens table, ending the session on the current device. Requires: Authorization: Bearer <token>

Example

curl -s -X POST https://your-api.example.com/api/auth/logout \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Response

{
  "message": "Successfully logged out"
}

Logout a specific device

POST /api/auth/logout_device Invalidates a specific session token (identified by its string value) without affecting the caller’s own active session. This enables users or admins to remotely terminate sessions on other devices. The target token is looked up in the user_tokens table; if not found, the endpoint returns HTTP 404. Requires: Authorization: Bearer <your_current_token>

Request fields

token

string

required

The full JWT string of the session you want to invalidate. This can be retrieved from the user_tokens table or a device-management endpoint.

Example

curl -s -X POST https://your-api.example.com/api/auth/logout_device \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9_CURRENT..." \
  -d '{"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9_OTHER_DEVICE..."}'

Response

{
  "message": "Successfully logged token out"
}

Email verification

After a successful call to POST /api/auth/register, the API sends a transactional email to the registered address. That email contains a code_user value (internally stored as the uniqd field on the user record). Submit that code to activate the account: POST /api/auth/verified_auth

Request fields

code_user

string

required

The unique verification code sent to the user’s email address after registration.

Example

curl -s -X POST https://your-api.example.com/api/auth/verified_auth \
  -H "Content-Type: application/json" \
  -d '{"code_user": "64f3c2a1b8e70"}'

Response

{ "message": 200 }

On success, the API sets email_verified_at to the current timestamp and clears uniqd. The account can now authenticate via /api/auth/login_ecommerce.

Until verified_auth is called, any attempt to log in via /api/auth/login_ecommerce will return HTTP 401, even if the email and password are correct.

Get authenticated user

POST /api/auth/me Returns the profile of the currently authenticated user. This endpoint requires a valid Bearer token. Requires: Authorization: Bearer <token>

Example

curl -s -X POST https://your-api.example.com/api/auth/me \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Response

{
  "name": "Jane",
  "surname": "Doe",
  "phone": "3001234567",
  "email": "jane@example.com",
  "bio": null,
  "fb": null,
  "tw": null,
  "sexo": null,
  "address_city": null,
  "avatar": "https://cdn-icons-png.flaticon.com/512/18851/18851107.png"
}

The avatar field returns a full URL. If the user has no uploaded avatar, a default placeholder URL is returned instead.

Request password-reset email

POST /api/auth/verified_email Sends a password-reset email containing a time-limited verification code to the specified address. The code is valid for 60 minutes. Use it with /api/auth/verified_code to confirm the code, then /api/auth/new_password to set a new password.

Request fields

string

required

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

Example

curl -s -X POST https://your-api.example.com/api/auth/verified_email \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com"}'

Response

{ "message": 200 }

Returns { "message": 403 } if no account with the given email address is found.

Verify password-reset code

POST /api/auth/verified_code Validates the reset code that was sent by /api/auth/verified_email. Returns success if the code exists and has not expired; returns an expiry error if the 60-minute window has passed.

Request fields

code

string

required

The reset code received in the password-reset email.

Example

curl -s -X POST https://your-api.example.com/api/auth/verified_code \
  -H "Content-Type: application/json" \
  -d '{"code": "64f3c2a1b8e70"}'

Response

{ "message": 200 }

Response value	Meaning
`{ "message": 200 }`	Code is valid and within the 60-minute window.
`{ "message": 401 }`	Code found but has expired.
`{ "message": 403 }`	Code not found.

Set new password

POST /api/auth/new_password Sets a new password for the account identified by the reset code. The code is consumed and cleared after a successful update, so it cannot be reused.

Request fields

code

string

required

The reset code previously validated with /api/auth/verified_code.

new_password

string

required

The new password to set on the account. The value is stored as a bcrypt hash.

Example

curl -s -X POST https://your-api.example.com/api/auth/new_password \
  -H "Content-Type: application/json" \
  -d '{"code": "64f3c2a1b8e70", "new_password": "newsecret123"}'

Response

{ "message": 200 }

Rate limiting

All routes under the /api/auth/ prefix are grouped under a throttle:10,1 middleware, which allows a maximum of 10 requests per minute per IP address. Exceeding this limit returns:

HTTP 429 Too Many Requests

The standard Retry-After header is included in the response, indicating how many seconds to wait before retrying. This limit applies equally to registration, login, refresh, and logout endpoints.

Get Started

Core Concepts

Deployment

Documentation Index

​Token format

​Register

​Request fields

​Example

​Admin login

​Request fields

​Example

​Response

​Customer login

​Request fields

​Example

​Response

​Token refresh

​Example

​Logout

​Example

​Response

​Logout a specific device

​Request fields

​Example

​Response

​Email verification

​Request fields

​Example

​Response

​Get authenticated user

​Example

​Response

​Request password-reset email

​Request fields

​Example

​Response

​Verify password-reset code

​Request fields

​Example

​Response

​Set new password

​Request fields

​Example

​Response

​Rate limiting

Build docs developers (and LLMs) love

Token format

Register

Request fields

Example

Admin login

Request fields

Example

Response

Customer login

Request fields

Example

Response

Token refresh

Example

Logout

Example

Response

Logout a specific device

Request fields

Example

Response

Email verification

Request fields

Example

Response

Get authenticated user

Example

Response

Request password-reset email

Request fields

Example

Response

Verify password-reset code

Request fields

Example

Response

Set new password

Request fields

Example

Response

Rate limiting