Worky Developers

API Authentication

Worky API uses JWT Bearer tokens for authentication. You authenticate via the Nova Direct Login endpoint using an API Service Account, then include the resulting access token in the Authorization header of all subsequent requests.

1. Create an API Service Account

An API Service Account is a technical user of type API_USER created in both Worky and Keycloak. Ask your Worky administrator to create one, or use the following endpoint if you have admin access:

Create API Service Account

curl -X POST "https://api-nova-dev.worky.mx/api/v1/users/api-service-accounts" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-integration",
    "roleId": <ROLE_ID>
  }'

The response includes a generatedPassword that you must store securely. This is the only time the password is returned.

Important: Never log or expose the generated password. Store it in a secrets manager or secure vault, not in source code.

2. Authenticate via Nova Direct Login

Use your service account credentials to obtain a JWT access token:

Nova Direct Login

curl -X POST "https://api-nova-dev.worky.mx/api/v1/users/id-provider/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-integration",
    "password": "YOUR_GENERATED_PASSWORD"
  }'

A successful response returns an access token:

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

3. Make Authenticated Requests

Include the access token in the Authorization header:

Example: List employees

curl -X GET "https://api-nova-dev.worky.mx/accounts/directory/api/v1/employees" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
  -H "Content-Type: application/json"

BFF Endpoints (Time & Attendance)

Time & Attendance operations go through the BFF (Backend for Frontend) layer, which requires an additional x-api-key header:

Example: Query shifts via BFF

curl -X POST "https://bff-nova-dev.worky.mx/api/time-and-attendance/shifts/query" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
  -H "x-api-key: YOUR_BFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "page": 1, "size": 20 }
  }'

Required Headers

Header	Value	Required
`Authorization`	Bearer <access_token>	Yes (all endpoints)
`Content-Type`	application/json	Yes
`x-api-key`	<BFF_API_KEY>	Yes (BFF endpoints only)
`Accept`	application/json	Recommended

Token Expiration & Refresh

Access tokens have a limited lifespan. Your application should handle token expiration by re-authenticating via the Nova Direct Login endpoint when you receive a 401 Unauthorized response.

Recommended: Decode the JWT to read the exp claim and proactively re-authenticate ~60 seconds before expiry to avoid request failures.

Password Rotation

API Service Account passwords can be rotated without downtime using the rotate endpoint:

Rotate password

curl -X POST "https://api-nova-dev.worky.mx/api/v1/users/api-service-accounts/rotate-password" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-integration"
  }'

Security: Rotate passwords periodically. In production, store all credentials (passwords and API keys) in a secrets manager, never in environment variables or source code.