SwipeClock
API Authentication
For information and code samples on authentication to the SwipeClock system, please visit https://developer.swipeclock.com/swipeclock-jwts.
Creation of the Originating Token
The Originating token is a JSON Web Token or JWT. You will need to get familiar with the following web site to facility creating and testing your tokens http://jwt.io
You will need to know Site Id, Accountant Id, Unix Timestamp, Product Type and SwipeClock API Secret. This information can be obtained from the "Client Level API Secret Management" and/or "Accountant Level API Secret Management" menu options.
Site Id
The Site ID or Site can be found in the "Client Level API Secret Management" or "Accountant Level API Secret Management" menu options.
Accountant Id
The Accountant Id or just Accountant This information can be obtained from the "Client Level API Secret Management" or "Accountant Level API Secret Management" menu options.
UNIX Timestamp
The Unix Timestamp is a standard measure for JWT's and must no more than 5 minutes into the future. You can find many web sites that can return a timestamp, here is one http://www.epochconverter.com
Product Type
The Product Type is used for accessing different products
and roles within those products. The Payload associated will also change
depending on the Product Type. Options are twppartner
, twpclient
, twpemp
, TSPartner
and TSEmp
. This document is focused on access to the TWP API's at the Partner and Client
level, so we'll be using the twppartner
and twpclient
types.
SwipeClock API Secret
To get the partner level secret using a Partner Login -> Accountant Menu and the
section labeled Accountant Administrative Tools -> there is an option called Accountant Level API Secret Management
to create and
retrieve the Partner level API secret. Your API secret is very important. Don't share it in an
accessible areas as it controls access to all your privileges.
To get the client level secret using a Partner Login -> Accountant Menu and the
section labeled Setting For Currently Selected Client -> is an option called Client Level API Secret Management
to create and
retrieve the Client level API secret. Your API secret is very important. Don't share it in an
accessible areas as it controls access to all your privileges.
When using a client login the client level secret can only be viewed. This can be obtained by the section labeled Settings Menu.
The option is called Client Level API Secret Management
.
Building Originating Token
Construct Partner level JWT with the following format.
HEADER
{
"typ":
"JWT",
"alg": "HS256"
}
PAYLOAD
{
"iss": [ACCOUNTANT ID],
"sub": "partner",
"exp": [UNIX TIMESTAMP],
"product": "twppartner",
"siteInfo": {
"type": "id",
"id": "[SITE ID]"
}
}
Important: Partner level JWT must be signed with the Partner level secret.
Construct Client level JWT with the following format.
HEADER
{
"typ":
"JWT",
"alg": "HS256"
}
PAYLOAD
{
"iss": [SITE ID],
"sub": "client",
"exp": [UNIX TIMESTAMP],
"product": "twpclient",
"siteInfo": {
"type":"id",
"id": "[SITE ID]"
}
}
Important: Client level JWT must be signed with the Client level secret.
Construct Login level JWT with the following format.
HEADER
{
"typ":
"JWT",
"alg": "HS256"
}
PAYLOAD
{
"iss": [SITE ID],
"sub": "client",
"exp": [UNIX TIMESTAMP],
"product": "twplogin",
"user": {
"type" : "login",
"id" : "[LOGIN]"
}
}
Important: Client level JWT must be signed with the Client level secret.
Construct Employee level JWT with the following format.
HEADER
{
"typ":
"JWT",
"alg": "HS256"
}
PAYLOAD
{
"iss": [SITE ID],
"sub": "client",
"exp": [UNIX TIMESTAMP],
"product": "twpemp",
"user": {
"type" : "empcode",
"id" : "[EMPLOYEE CODE]"
},
"siteInfo": {
"type" : "id",
"id" : "[SITE ID]"
}
}
Important: Client level JWT must be signed with the Client level secret.
Signature
Use the SwipeClock API secret to sign the token. On the
jwt.io site it's labeled as secret
.
Problems Creating Token
Occasionally the jwt.io site will indicate that the token is invalid. Add or remove a character out of the PAYLOAD section, then undo your change. This will refresh the token creation and should result in a valid signed token.
Calling Authentication Service
Your token is good for a short period of time so you should call to receive the JWT API token very soon after having constructed your Originating token. We utilize a tool call POSTman, a plug in to the Chrome browser to manually make calls. You will need to do an HTTPS POST to the following URL:
POST https://clock.payrollservers.us/AuthenticationService/oauth2/usertoken
In the header add "Authorization", "Bearer {Originating Token}, add header "Content-Type" of type "application/json". In POSTman it looks like:
Sample: Response
{ "token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOjEyMzQ1LCJzdWIiOiJhY2NvdW50YW50IiwiZXhwIjoyMDcxMzAzMTcwLCJwcm9kdWN0IjoidHdwcGFydG5lciIsInNpdGVJbmZvIjp7InR5cGUiOiJpZCIsImlkIjoiNjc4OSJ9fQ.8L4CVAP6I4TVpjXLck8knpC8YDWG0xMd0h2j2bm05DU"
}