🔒 Authentication

Authentication is the heart of Securial. It provides secure, stateless sessions using signed tokens that travel with each request.

📤 Logging in

Send a POST request to /login with your email_address and password. On success, the response includes:

• A session token – Include this in the Authorization: Bearer header on future requests.
• A refresh token – Store this securely on the client (e.g., in an HTTP‑only cookie). Use it to obtain a new session token when your current one expires.

If the credentials are invalid or the user’s password has expired, the response will be 401 Unauthorized with an error message.

🔄 Refreshing a session

Session tokens have a short lifespan (configured via session_expiration_duration). To stay signed in without asking the user to log in again, call /refresh with the refresh token in the refresh_token param. The response contains a new session token and refresh token. Each refresh increases the refresh_count on the session.

🚪 Logging out & revoking

• DELETE /logout – Revokes the current session, making its session token unusable.
• DELETE /revoke_all – Revokes all sessions and refresh tokens for the current user across all devices.

🛡️ Session model

Sessions are stored in the Securial::Session model and track the user, IP address, user agent, refresh token and expiration. Methods include:

• revoke! – mark a session as revoked.
• refresh! – generate a new refresh token and update expiry (raises an error if the session is revoked or expired).
• expired? and revoked? – check the session state.

You rarely interact with the Session model directly; Securial takes care of creating and updating sessions when users log in or refresh.

🔒 Security best practices

• Always use HTTPS to protect tokens in transit.
• Store session tokens in memory (e.g., Vuex, Redux) and refresh tokens in secure, HTTP‑only cookies.
• Rotate your session_secret carefully — doing so invalidates existing sessions.
• For long‑running clients, use /refresh periodically rather than storing long‑lived session tokens.