Overview

When I Work provides an open API (application program interface) to allow your custom applications to interact and exchange data with When I Work. Our API follows standard conventions with logically grouped methods.

For more information, check out our API documentation.

Request access

Customer implementations

If you’re a new customer that wants to leverage our API for your custom implementation, you will need the following information.

• Company using When I Work
• When I Work admin Name
• Developer contact information
  • Name
  • Email
  • Phone Number
• Intended Use

When you have this information, send us an email with your Access Request.

Third party integrations

If you’re a third party company that wants to integrate with our API to build custom integrations for your customers, we’d love to discuss our partnership program with you. Please complete the form on the Partners Page to get a dialogue going.

Authentication

Authentication with When I Work is based on a token model. First, you authenticate using a private developer key and the username and password of a When I Work user. Your developer key can be used like the following in the headers.

curl -X POST 
  https://api.login.wheniwork.com/login 
  -H 'W-Key: <INSERT_DEVELOPER_KEY_HERE>' 
  -H 'content-type: application/json' 
  -d '{"email":"<INSERT_USERNAME_HERE>","password":"<INSERT_PASSWORD_HERE>"}'

Authenticating returns back a person object containing a token that is used to authenticate all future requests. The token may be included in the headers, as a cookie, or in the query string using the key ‘W-Token’ or ‘Authorization’. You can now use this token to fetch all the users tied to your person.

curl -X GET 
  'https://api.wheniwork.com/2/login?show_pending=true' 
  -H 'Host: api.wheniwork.com' 
  -H 'Authorization: Bearer <INSERT_TOKEN_HERE>'

You can use this list of user objects, each of which is associated with a When I Work account. You can use the user ID to set the context for which account you will be acting as by providing a When I Work user ID through the ‘W-UserID’ header. For example, to fetch all users in the account belonging to the When I Work user with id 5, you would include the following header in your request:

curl -X GET 
  https://api.wheniwork.com/2/users 
  -H 'Authorization: Bearer <INSERT TOKEN HERE>' 
  -H 'W-UserId: 5'

You can find additional authentication related API documentation in our Login Service API docs.

Token refresh

All token refresh requests must be authenticated using the current login token. After you’ve successfully retrieved a new token, discard your old token and use the new one for all requests going forward.

How to refresh

Example curl to refresh your token:

curl -X POST 
  https://api.login.wheniwork.com/refresh
  -H 'Authorization: Bearer <INSERT_TOKEN_HERE>'

When to refresh

The API imposes no limit on how often you can refresh a token. However, all implementations of the refresh action should assume that a token expires 7 days after its creation. You can determine the expiration date by requesting the ‘iat’ (issued at) claim from the token and then add 7 days (604800 seconds). A token should be refreshed at least 2 days before expiration (432000 seconds after the token was issued).

If the token is missing the ‘iat’ claim, refresh immediately.

You can find additional authentication related API documentation in our Login Service API docs.