Skip to content
  • There are no suggestions because the search field is empty.

How to Use the Timecloud Public API

The Timecloud Public API lets you connect external systems — payroll tools, HRIS platforms, scheduling engines, or custom dashboards — directly to your Timecloud data. Use it to automate employee management, roster scheduling, attendance tracking, and more.

Getting Started

  • Company admins can create and manage API keys directly from the Timecloud web app (see Managing Your API Keys below).
  • You will need a dedicated API user account - a separate employee record created specifically for your integration. This account authenticates API requests and cannot sign in to the web app, mobile app, or kiosk. See Setting Up a Dedicated API User below.
  • All API communication happens over HTTPS.

Authentication

  1. Call the /oauth/token endpoint with your API user's Client ID and Client Secret (provided by your Timecloud account manager).
  2. You'll receive a Bearer token.
  3. Include this token in the Authorization header of all subsequent requests:
    Authorization: Bearer <your-token>
  4. Include your API key in the X-Timecloud-Integrator-Key header:
    X-Timecloud-Integrator-Key: <your-api-key>

Managing Your API Keys

Company admins can create, view, and revoke API keys directly from the web app.

Where to find it

  • Go to Settings > API Integration.

Screenshot 2026-09-18 at 2.57.19 PM

Creating a key

  1. Click Create New Key.
  2. A dialog displays the new key. Copy it immediately - the key is shown only once and cannot be retrieved later.
    1. Store the key securely (e.g. in a secrets manager or password vault).

Screenshot 2026-09-18 at 3.00.23 PM

Viewing your keys

  • The API keys table shows every key with its Created date and Status (Active or Revoked).

Screenshot 2026-09-18 at 3.02.55 PM

Revoking a key

  1. Click Revoke next to the key you want to disable.
  2. Confirm in the dialog. This cannot be undone - any integration using the revoked key will stop working immediately.

Screenshot 2026-09-18 at 3.02.46 PM

Tip: You can have up to 100 active keys at a time. If you need a new key, revoke an unused one first.

Setting Up a Dedicated API User

API authentication requires a dedicated employee account that exists solely for your integration. This account cannot sign in to the Timecloud web app, mobile app, or kiosk - it is restricted to API access only.

Why a dedicated account?

  • API user accounts are blocked from all interactive sign-in (web app, mobile app, kiosk). You cannot use a regular admin's credentials for both the web app and the API.
  • Using a dedicated account keeps your integration's access separate from any individual person's login, which makes it easier to manage permissions and audit API activity.
  • If someone leaves the company, your integration keeps working because it does not depend on a personal account.

Recommended email format

Create the API user with a clearly identifiable, non-personal email address. For example:

  • api-user@yourdomain.com
  • timecloud-api@yourdomain.com
  • integrations@yourdomain.com

Avoid using a real person's email. A shared or service-account email makes it clear the account is for system use and prevents disruption if a team member's email is deactivated.

  1. Step-by-step setup

    1. Go to Employees and click Add Employee.
    2. Enter the API user's details (e.g. first name "API", last name "User", email api-user@yourdomain.com).
    3. After the employee record is created, open their profile.
    4. Navigate to the User Access tab.
    5. Enable Admin Access and set a password.
    6. Toggle API User on.

Screenshot 2026-09-18 at 3.05.27 PM

Important: Once API User is enabled, the account is locked to API-only access. If someone attempts to sign in with this account via the web app, mobile app, or kiosk, they will see: "This account type can't sign in here. Please contact Timecloud support if you need access."

  • This applies to password sign-in, PIN sign-in, and Microsoft sign-in.
  • API user accounts are automatically exempt from two-step verification requirements.
  • Turning off the API User toggle removes the integration's ability to authenticate as that employee. A confirmation dialog warns you before saving.

Controlling access to API Integration settings

  • Company admins have access by default.
  • Sub-admins need the API Integration Screen permission enabled in Feature Access (under System Administration & Security).

Screenshot 2026-09-18 at 3.06.41 PM

Date & Time Format

  • Request date fields: YYYY-MM-DD (e.g. 2024-01-15)
  • Response date-time fields: ISO 8601 UTC (e.g. 2024-01-15T09:30:00.000Z)
  • All times are returned in UTC.

Need Help?

Reach out to your Timecloud account manager or contact support@jointimecloud.com for API access, troubleshooting, or integration guidance.