Authentication

JWT, shared punch terminals and registered kiosk devices.

Curio Time uses three auth models depending on integration type. Use the one that matches your product.

1. JWT Bearer (HR / payroll / BI)

Standard integration API calls:

Authorization: Bearer {accessToken}
Content-Type: application/json

Login

POST /api/v1/auth/login

{
  "email": "integration@company.example",
  "password": "…"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJ…",
    "refreshToken": "…",
    "accessTokenExpiresAtUtc": "2026-08-25T11:00:00Z",
    "refreshTokenExpiresAtUtc": "2026-09-24T10:00:00Z"
  },
  "errors": null
}

Refresh

POST /api/v1/auth/refresh

{
  "refreshToken": "…"
}

Recommended roles

2. Shared punch terminal (no JWT)

For web punch clocks and third-party terminals that authenticate the employee per punch with password (same as Curio’s /punch-clock page).

• No Authorization header
• companyId in query or body scopes the tenant
• Rate limited (punch policy)

Endpoints: Punch clock — Option A

3. Registered kiosk device (device token + PIN)

For hardware kiosk partners (tablets, time clocks) that register once and then use a 4-digit kiosk PIN per employee.

1. Register device → deviceToken (Bearer)
2. Employee enters PIN → X-Employee-Token
3. Punch with both headers

Endpoints: Punch clock — Option B

Health check (no auth)

GET /api/v1/health

Use for uptime monitoring only.

Security practices

• Never store passwords, refresh tokens, device tokens, or PINs in client-side web apps or git
• Use HTTPS only
• Revoke compromised sessions: POST /api/v1/auth/revoke
• Use dedicated service accounts — not personal employee logins
• Kiosk device registration requires owner/manager credentials once; store deviceToken securely on the device

OAuth2 / API keys (planned)

Future releases may add OAuth2 client credentials or company-scoped API keys with scopes and audit logs. v1 may use JWT service accounts for HR integrations.