Authentication

Access

Justworks Hours for Developers uses OAuth2 for authentication. OAuth2 allows trusted third-party developers to access limited information on behalf of customers without seeing or storing customer credentials.

To protect our customers' sensitive information, API access is granted upon request and review by the Justworks Hours integration team. To obtain access to Justworks Hours for Developers, please contact [email protected]

Obtaining Tokens

Access tokens may be obtained via the password or the authorization_code grant type.

Password grant type
See docs here: https://developers.justworkshours.com/v4.0/reference#get-token

Authorization code (Redirect) grant type

<a href="https://hours.justworks.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code">Connect to Justworks Hours</a>

The above link (with your credentials) will take the user to Justworks Hours' website and will be prompt them to log in using their Justworks Hours account. Once login is complete, Justworks Hours will generate an authorization code and the user will be redirected to the redirect_uri with that code attached. In this case, the user will be sent to a url like this:

https://website.com/callback?code=JUSTWORKS_HOURS_AUTHORIZATION_CODE
This parameter contains the authorization code that you will then use to obtain your first access token.

Then submit a POST request to https://hours.justworks.com/oauth/token with the following parameters:

  • client_id - your client id
  • client_secret - your client secret
  • redirect_uri - the encoded url you submitted when signing up for JHFD.
  • code - the code being exchanged for an access token. This should be the authorization code received in the previous step.
  • grant_type - this should be authorization_code

The Justworks Hours API will respond with a JSON payload similar to the following:

{
  "access_token": "UNIQUE_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "UNIQUE_REFRESH_TOKEN"
}

The access_token in the above request can be used to authenticate API requests on behalf of the given customer. This token is good for 7200 seconds from the time of issuance. Continued access is available by using the refresh_token to obtain a new access token

Refreshing Tokens

To obtain a refresh token, submit a POST request to https://hours.justworks.com/oauth/token with the following parameters:

  • client_id - your client id
  • client_secret - your client secret
  • redirect_uri - the encoded url you submitted when signing up for BFD.
  • refresh_token - the refresh_token being exchanged for an access token code.
  • grant_type - this should be refresh_token

The Justworks Hours API will respond with a JSON payload similar to the following:

{
  "access_token": "UNIQUE_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "UNIQUE_REFRESH_TOKEN"
}

Each refresh token may be used only once.

Authenticating Requests

Requests to Justworks Hours API endpoints can be authenticated using a Bearer token in the HTTP request headers, as follows.

Content-Type: application/json
Authorization: Bearer UNIQUE_ACCESS_TOKEN

Help and Support

For support inquiries around our API, please email [email protected]