Authentication

PosStar uses JWT (JSON Web Tokens) for authentication. Obtain a token via the login or register endpoint, then include it in the Authorization header of all API requests.

Important: Tokens expire after 24 hours. Use the refresh endpoint to obtain a new token before expiry. Store tokens securely — never expose them in client-side code or URLs.

POST/api/v1/auth/login

Authenticate with email and password

Request Body

{
  "email": "user@example.com",
  "password": "your-password"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "admin",
    "vendor_id": "uuid"
  }
}

Returns a JWT token valid for 24 hours. Include this token in the Authorization header for all subsequent requests.

POST/api/v1/auth/register

Register a new vendor account

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "min-8-characters",
  "business_name": "My Store",
  "industry": "retail"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "admin",
    "vendor_id": "uuid"
  }
}

Creates a new vendor with a default store. The registering user becomes the admin. Industry can be: retail, restaurant, distribution, salon, pharmacy, grocery.

GET/api/v1/auth/me

Get the current authenticated user profile

Response

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin",
  "vendor_id": "uuid",
  "store_id": "uuid",
  "avatar": null,
  "created_at": "2025-01-15T10:00:00Z"
}

Requires a valid JWT token in the Authorization header.

POST/api/v1/auth/refresh

Refresh an expiring JWT token

Request Body

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}

Exchange a valid (not yet expired) token for a new one. Use this to keep sessions alive without re-authenticating.

POST/api/v1/auth/forgot-password

Request a password reset email

Request Body

{
  "email": "user@example.com"
}

Response

{
  "message": "If the email exists, a reset link has been sent."
}

Always returns 200 regardless of whether the email exists, to prevent email enumeration.

Error Responses

401

Unauthorized

Token is missing, invalid, or expired. Re-authenticate to get a new token.

403

Forbidden

The authenticated user does not have permission for this action (e.g., cashier trying admin endpoints).

409

Conflict

Email already registered (on register endpoint).