Subscriptions & Features Featured

White-label API: Active Employee Tracking Sessions

How an approved customer system can authenticate with WorkPulse and list employees who are actively tracking time right now.

68 views

6 min read

Updated 56 minutes ago

#api #white-label #active-sessions #tracking #integrations

White-label API

Active employee tracking sessions

Use this endpoint when an approved customer system needs to show which employees are actively tracking time in WorkPulse right now. The response is tenant-scoped and only includes open sessions where end_time IS NULL.

Endpoint

GET /api/white-label/v1/active-sessions

Refresh every 30 to 60 seconds for a live status panel.

What it returns

Employee

User ID, name, and email for each active session.

Work context

Project, team, and session type when those records are attached.

Live timing

Start time, current duration in seconds, and server generation time.

State

Last activity, idle fields, break status, and active break start time.

Access requirements

The company tenant has the API Access feature enabled.

Customer API client security is configured for the tenant.

The request uses an allowed origin or sends X-WorkPulse-Client-Key.

The API user has View Users or View All Captures.

The request includes a valid Sanctum bearer token from the white-label login flow.

Authentication flow

Step 1

Login

Send the manager or integration user credentials to the white-label login endpoint.

POST /api/white-label/v1/auth/login
Accept: application/json
Content-Type: application/json
X-WorkPulse-Client-Key: YOUR_CLIENT_KEY

{
  "email": "manager@example.com",
  "password": "password",
  "tenant_id": "optional-tenant-id"
}

Step 2

Select tenant when required

If login returns requires_tenant_selection: true, exchange the temporary token for a tenant token.

POST /api/white-label/v1/auth/select-tenant
Accept: application/json
Content-Type: application/json
Authorization: Bearer TEMP_TOKEN
X-WorkPulse-Client-Key: YOUR_CLIENT_KEY

{
  "tenant_id": "tenant-id-from-login-response"
}

Step 3

List active sessions

Call the active sessions endpoint with the tenant token.

GET /api/white-label/v1/active-sessions
Accept: application/json
Authorization: Bearer TENANT_TOKEN
X-WorkPulse-Client-Key: YOUR_CLIENT_KEY

Example cURL

curl -X GET "https://your-workpulse-domain.com/api/white-label/v1/active-sessions" -H "Accept: application/json" -H "Authorization: Bearer TENANT_TOKEN" -H "X-WorkPulse-Client-Key: YOUR_CLIENT_KEY"

Example response

{
  "generated_at": "2026-08-18T14:30:00+00:00",
  "active_sessions_count": 2,
  "active_sessions": [
    {
      "id": 456,
      "user": {
        "id": "user-uuid-or-id",
        "name": "Employee Name",
        "email": "employee@example.com"
      },
      "project": {
        "id": 10,
        "name": "Project A"
      },
      "team": {
        "id": 2,
        "name": "Support Team"
      },
      "type": {
        "id": 1,
        "name": "Desktop"
      },
      "started_at": "2026-08-18T13:20:00+00:00",
      "duration_seconds": 4200,
      "last_activity_at": "2026-08-18T14:28:00+00:00",
      "idle_prompt_sent_at": null,
      "idle_expires_at": null,
      "idle_accumulated_seconds": 0,
      "is_on_break": false,
      "break_started_at": null
    }
  ]
}

Field notes

Field	Meaning
generated_at	Server time when the response was created.
active_sessions_count	Number of open sessions for the tenant.
active_sessions	Sessions where `end_time` is null.
duration_seconds	Calculated from `started_at` to `generated_at`.
last_activity_at	Most recent tracked activity or heartbeat time when available.
is_on_break	True when the session has `break_start` and no `break_end`.

Common errors

401 Unauthorized

Bearer token is missing, expired, or invalid.

403 Forbidden

API Access is disabled, the origin or client key is not allowed, or the user lacks permission.

422 Validation

Integration checklist

Enable the API Access feature for the tenant.

Configure Allowed Origins for browser clients or generate a client key for private server integrations.

Create or choose a WorkPulse user with View Users or View All Captures.

Select a tenant if the login response requires it.

Call /api/white-label/v1/active-sessions with the tenant token.

Refresh on a reasonable interval, such as every 30 to 60 seconds.

Treat an empty active_sessions array as no employees currently tracking.

Was this article helpful?