Dev Support

☰ Documentation

Creating a JWT Header & Signature

Creating a JWT Header

The first part of your JWT will be the header. This identifies the algorithm and token type you are using. Included in the JWT header are:

Name Type Description
alg String Identifies the hashing algorithm used being used. Use “HS256”.
typ String Identifies the type of token which is JWT. Use “JWT”.

Below is an example of a header of a JWT:

{ 
  alg: "HS256", 
  typ: "JWT" 
}

Creating a JWT Body/PayloadJWT claims that are required for the originating token are described below:

Name Type Description
iss Number This is the issuer and is either the WFH Accountant ID or Client/Site ID, depending on the secret you use to sign the originating token.
product String This indicates the type of token that will be generated. Use twppartner or twpclient respectively when generating a token for your integration to call WFH API with an Accountant-level secret or a Client-level secret. For Single-Sign-On, use twpemp to sign in as a regular employee, or use twplogin to sign in as an accountant-level user.
sub String This is the subject and should set to “partner” if you are using an accountant-level token or “client” if you are using a client/site-level token.
exp String This is the UNIX epoch UTC timestamp at which the JWT token request expires. Our authentication service allows some leeway in both directions to account for clock skew, but the expiration time should be no more than 5 minutes in the future. Visit https://www.epochconverter.com/ for more information.
siteInfo Object This indicates which Client Site the API endpoint calls should apply to and is an object of name value pairs: type and id.

If the type key has a value of “id”, the id key should use the Client’s Site ID as its value.

If the type key has a value of “workforcehubcompanyid”, the id key should use the client’s Company Code as its value.

siteInfo is required if you are generating a token using a client secret.  When using an accountant secret, siteInfo should be provided if you are making updates to a specific site.

There are limited api calls you can use with a non-site specific token, such as creating a new company or getting a list of all companies under the accountant.
User (Used only for SSO) Object

An object of name value pairs (type and id):

If the type key has a value of “id”, Type should be:

  • “empcode” if you’re identifying the employee by their ID/code from the source payroll platform
  • “id” if you’re identifying the employee by their SwipeClock clock number
  • “login” if you’re identifying the login/username you’d like to SSO into

If the type key has a value of “workforcehubcompanyid”, Type should be:

  • workforcehubemployeeid if you’re identifying the employee by their WorkforceHub Employee ID
  • empcode if you’re identifying the employee by their ID/code from the source payroll platform

SAMPLE JWT PAYLOAD

{
     "iss": 9823812,
     "exp": 1556216565,
     "sub": "partner",
     "siteInfo":
     {
         "type": "id",
         "id": 78694
     },
     "product": "twppartner"
}

Creating a JWT Signature

The last part of the JWT will be the signature. This is the result of taking the base64 encoding of the header, base64 encoding of the payload and your API secret and signing it with the selected hashing algorithm.

You can view a working example of creating your full JWT in the Authentication Service in github.