Authentication

The Auth endpoints handle user login, logout, and token refresh. MySagra uses JWT-based authentication with short-lived access tokens and long-lived refresh tokens stored as HTTP-only cookies.

Token Lifecycle

Bearer Token Authentication

Use the JWT access token in the Authorization header for all protected API endpoints:

Authorization: Bearer <accessToken>

The token is valid for 15 minutes. When it expires, use the refresh token to obtain a new one.

API Key Authentication

Certain services (MyStampa, MyClienti) authenticate using an API key instead of a JWT. Include the key in the X-API-KEY header:

X-API-KEY: ms_pt_<key>

or

X-API-KEY: ms_wb_<key>

API keys are created via the API Keys endpoints and are specific to service integrations. They are accepted only by endpoints that explicitly support API key authentication.

POST /auth/login

Authenticate a user with username and password.

Authentication: None required

Request Body

{
  "username": "admin",
  "password": "password123"
}

Response 200 OK

The refresh token is automatically set as an HTTP-only cookie named refreshToken (expires in 7 days).

{
  "user": {
    "id": "clxyz123456789abcdef",
    "username": "admin",
    "role": "admin"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Errors

POST /auth/logout

Revoke a refresh token to log out from a specific session.

Authentication: Cookie (refreshToken)

The refresh token is automatically read from the refreshToken HTTP-only cookie.

Response 200 OK

Empty response — the refresh token has been revoked.

Errors

POST /auth/refresh

Generate a new access token using the refresh token cookie.

Authentication: Cookie (refreshToken)

Response 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Errors