Development Options For Any Integration

TIMEKEEPING ANYWHERE

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
client
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
twpclient
twppartner
tsemp
tspartner
twplogin
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.

Siteinfo


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
extid
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.

User


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
twpclient
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

pushactivity50

Payroll Interfaces

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

pushactivity50

Basic Automation

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

pushactivity50

Component Options

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

LEARN MORE

pushactivity50

APIs

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

LEARN MORE