Understanding SwipeClock JWTsCode Samples

In order to make API calls, one must obtain a JSON Web Token. A JWT serves several purposes:

  • Authenticates the caller
  • Target a specific site or employee.

Once generated, a JWT is passed in the HTTP Header for all API calls.

Generating a JWT

The basic idea behind generating a JWT is this:

  • Create a token
  • Sign the token with a secret
  • Submit the token to the Authentication Service. If successful, a JWT will be issued.

Creating a token

A JWT is an encoded and cryptographically-signed JSON object. For more details and a tool to manually craft a JWT, visit jwt.io

A sample token:

  "iss": 1234,
  "exp": 1481228804,
  "iat": 1481228534,
  "product": "twppartner",
  "siteInfo": {
    "type": "Id",
    "id": 5543

User-Defined Token Components

This table shows what values you can set in your token creation. Note: Additional properties may be injected into this document as part of the final JWT.

Note: Properties are case sensitive. Values are case insensitive.

Property Required Possible Values Description
iss yes integer Issuer. This is either an Accountant Id or Site Id.
sub no* partner
Subject. The type of ApiSecret used to sign the token. An accountant-level ApiSecret corresponds to partner, a site-level ApiSecret corresponds to client.
This is required if product is either twpemp or twplogin.
exp yes integer Expiration. The EPOC time the token expires
iat no integer The EPOC time the token was issued.
product yes twpemp
The product.
siteInfo no* JSON Site information used to specify a site. Some product types require this.
user no* JSON User information to target a specific employee. Some product types require this.

For various types of tokens, a guide is provided later in this document to aid you in generating the correct JSON token.

Partner-level vs Client-level

If a partner assists a client with an integration, they can keep their partner-level API Secret a secret by creating a client-level token using the client Id as the issuer.

Product Types

Type Description ApiSecret to use Dependant Properties Accessible APIs
twpemp A Time Works Plus employee token. Requires subject to be set. Partner or Client siteInfo, user TimeWorksPlus
twpclient A site-level Time Works Plus generic token.
This will have permissions to all employees for the site.
Client   TimeWorksPlus
twppartner A partner-level Time Works Plus generic token.
This will have permissions for all sites and all sites’ employees the partner has access to.
Partner siteInfo TimeWorksPlus
tsemp A Time Simplicity employee token. Specific to an employee within Time Simplicity. Partner siteInfo, user TimeSimplicity
tspartner A Time Simplicity partner token. Access for all employees for all sites the partner has access to. Partner siteInfo TimeSimplicity
twplogin A login used for single sign on. Requires subject and user.type = login|loginguid to be set.
Cannot be used for regular TWP API calls.


The siteinfo property provides information about which site is targeted by the JWT and is required when product = twpclient. The most commonly-used type is id. Sample:

  "siteinfo": {
    "type": "id",
    "id": "1234"
Property Possible Values Description
type id
This determines the type of id in the id property. The most common is id.
extid can only be used when product = tsemp or tspartner.
id string The id, which type is determined by the type property.


twpemp and twplogin products require the user property to specify which employee to use. Sample:

  "user": {
    "type": "id",
    "id": "375637"
Property Possible Values Description API Support
type   This determines the type of id in the id property.  
  id The employee’s Id– the internal Time Works Plus unique identifier. TWP, TS
  guid The employee GUID in Time Works Plus. TWP
  empcode The employee code. This is most often an employee’s unique identifier from an external system that integrates with Time Works Plus. TWP, TS
  extid Time Simplicity only. The external id of the user. TS
  extguid Time Simplicity only. The external GUID of the employee. TS
  login An employee’s login. Used only with product=twplogin SSO
  loginguid An employee’s login guid. Used only with product=twplogin SSO
id string The id, which type is determined by the type property.  

Enumerated Token Types

The table below details the various token-types and what fields are required for each. If a cell is empty, then the value should not be included in the token. Work with your account manager to determine which SiteInfo and User identifiers to use.

Product Subject SiteInfo User
twpemp partner id id
twpemp partner id guid
twpemp partner id empcode
twpemp client id id
twpemp client id guid
twpemp client id empcode
twppartner   id  
tsemp   id id
tsemp   id extid
tsemp   id extguid
tsemp   extid id
tsemp   extid extid
tsemp   extid extguid
tspartner   id  
tspartner   extid  
twplogin partner   login
twplogin partner   loginguid
twplogin client   login
twplogin client   loginguid


Payroll Formats

Payroll interfaces for all major systems. Hundreds of formats for smooth data transfer.

Quick Start Library

SSO to SwipeClock for iframe direct access to employee and payroll data and accruals.


Embeddable Widgets

Component-level functionality for different timekeeping activities (punch clock, time cards, time-off requests, etc.).



Extend SwipeClock timekeeping features to other applications including self-service portals, HR platforms and payroll solutions.