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

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

APIs

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