Complete guide to device authentication using localStorage
The service account authentication system allows kiosks, tablets, and other devices to authenticate without interactive login. This system uses localStorage instead of cookies to store session tokens, making it compatible with all browsers and devices.
An administrator provisions a new device at /admin/devices, specifying the device name, identifier, and role. A long-lived refresh token is generated and shown once.
The device exchanges the refresh token for a session token by calling /api/auth/device/token. The session token is stored in localStorage.
On each page load, the device validates its session token by calling /api/auth/device/validate. If valid, the user information is retrieved.
The device's role determines what pages and features it can access. Permissions are checked on each request based on the authenticated user's role.
/api/auth/device/tokenExchange a refresh token for a session token
Request:
{
"refresh_token": "your-refresh-token-here"
}Response:
{
"success": true,
"session_token": "session-token-here",
"expires_at": "2026-01-20T12:00:00Z",
"user": {
"id": 123,
"name": "Device Name",
"email": "device@serviceaccount.local",
"role": "signintablet"
}
}/api/auth/device/validateValidate a session token and get user information
Request:
{
"session_token": "your-session-token-here"
}Response:
{
"success": true,
"valid": true,
"user": {
"id": 123,
"name": "Device Name",
"email": "device@serviceaccount.local",
"role": "signintablet"
},
"session": {
"sessionToken": "session-token-here",
"expires": "2026-01-20T12:00:00Z"
}
}Complete authentication management including login, logout, and session validation.
const {
isAuthenticated,
isLoading,
user,
error,
authenticateDevice,
validateSession,
logout
} = useDeviceAuth();
// Authenticate with refresh token
await authenticateDevice(refreshToken);
// Validate current session
await validateSession();
// Logout
logout();Simplified hook for getting current user information.
const { data: user, loading, error, refetch } = useDeviceUser();
if (loading) return <div>Loading...</div>;
if (error) return <div>Error: {error}</div>;
if (!user) return <div>Not authenticated</div>;
return <div>Welcome, {user.name}!</div>;| Key | Description |
|---|---|
| device_session_token | The current session token used for authentication |
| device_session_expires | ISO 8601 timestamp when the session expires |
| device_user | JSON string containing cached user information |
Store refresh tokens securely
Never commit refresh tokens to version control. Use environment variables or secure configuration management.
Revoke compromised tokens immediately
If a device is lost or a token is compromised, revoke it at /admin/devices and provision a new device.
Use appropriate roles
Assign the minimum required role for each device. Sign-in tablets should use the "signintablet" role, not "admin".
Monitor device usage
Regularly review the "Last Used" timestamp in the device management page to identify inactive or suspicious devices.