Harvest API V1 has been unsupported since January 1st, 2019, and it will be removed soon.

To migrate your integration from API V1 to API V2, you will need to introduce changes to support the expected request and response formats of API V2, as reflected in the documentation.

This guide covers the paths for migrating the authentication flow of your integration from API V1 to API V2, as well as some additional requirements when making requests to API V2.

Migrating from API V1 to API V2 Authentication

Migrating Integrations Using Basic Authentication

Basic Authentication is not supported by API V2, as there currently are more secure alternatives available. To migrate your integration to API V2, you can replace Basic Authentication with a Personal Access Token.

You can create a Personal Access Token in the Developers section of Harvest ID, and use it within an Authorization: Bearer header.

The API V2 documentation describes how to use Personal Access Tokens.

Migrating Integrations Using OAuth2 Implicit Grant Flow

API V2 supports the standard OAuth2 Implicit Grant Flow, too, as described in the API V2 documentation.

Compared to the OAuth2 Implicit Grant Flow in API V1, there are some changes that you will need to introduce in your integration:

• You will need to create an OAuth2 application for your integration in the Developers section of Harvest ID.
• For API V2, the host for the OAuth2 Implicit Grant Flow is id.getharvest.com, whereas the host for OAuth2 flows in APIv1 was api.harvestapp.com.
• Access tokens obtained through API V1 are not valid in API V2. When you make the switch to using API V2 in your integration, your users will need to reauthorize the integration, by going through the authorization flow of API V2.

Migrating Integrations Using OAuth2 Authorization Code Flow

API V2 supports the standard OAuth2 Authorization Code Flow, too, as described in the API V2 documentation.

Compared to the OAuth2 Authorization Code Flow in API V1, there are some changes that you will need to introduce in your integration:

• You will need to create an OAuth2 application for your integration in the Developers section of Harvest ID.
• For API V2, the host for the OAuth2 Authorization Code Flow is id.getharvest.com, whereas the host for OAuth2 flows in APIv1 was api.harvestapp.com.
• For API V2, the host for the OAuth2 token endpoint is id.getharvest.com.
• Access tokens and refresh tokens obtained through API V1 are not valid in API V2. When you make the switch to using API V2 in your integration, your users will need to reauthorize the integration, by going through the authorization flow of API V2.

API V1 to API V2 OAuth2 token migration endpoint

If you maintain an integration with API V1 that uses the OAuth2 Authorization Code flow, you can use the token migration endpoint to exchange each valid API V1 refresh token you hold on behalf of your users for an API V2 access token / refresh token pair.

The goal of the token migration endpoint is that maintainers of third party integrations can obtain valid OAuth2 access / refresh token pairs ahead of making the switch to API V2. When the integration makes the switch to API V2, it will be able to use the access and refresh tokens obtained through the migration endpoint, and avoid an interruption of service for users of the integration — your users won’t need to go through the API V2 OAuth2 authorization flow.

As a maintainer of the integration, to exchange API V1 tokens for API V2 tokens you will need:

• A valid API V1 refresh token for each user whose tokens you want to migrate.
• The client ID and secret of your OAuth2 app for API V1.
• The client ID and secret of the OAuth2 app you will be using for API V2.
• Your own User-Agent string, so we can use it to help you debug any issues.

To migrate a single API V1 refresh token, send a POST request to https://id.getharvest.com/api/v2/oauth2/migrate, with the following parameters:

Example Request

curl -X POST https://id.getharvest.com/api/v2/oauth2/migrate \
-H "User-Agent: [email protected] Token Migration Script" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '
{
  "v1_refresh_token": "rmf1R2wjemHQQwlmlkfpccTXxBV8CAEt2rm6hogaS26txQw3P6dqwNoYGsg47poTnTI_WmKcfI7stCsrbqUTTA",
  "v1_client_id": "TPs7xbUXjmR8TTfPdUnDEQ",
  "v1_client_secret": "73H0ym6HHi6qrO_rxCuJZ4-cNvaPDgwCaEFLSUT9eze79zOSTPZrQBB45AsZ0zVhxl0lXmc4XJuN86u3z77o8Q",
  "v2_client_id": "rwJrBf5ngu0vP9r6HgsnNLU2",
  "v2_client_secret": "l35kDpP5PLGp5JlZ3SCtUiKBPxTj3O1EZ_dNJ_igN_vQBpuXQ_X_VvcD6XAk6kw0MJ-KXp3yaGFgMRfd6bmVwQ"
}'

{
  "access_token": "1.at.4jsI8k6v2VJSvdbC9mLn1PhoLW1GcCy38w9snxXQlJOSuM_B-YmR30IjgMDkUFNxbfcmVRwq7xYBvXkxlH3Hhw",
  "refresh_token": "1.rt.r423dUyUXxgtCzK-uaBrWPbMYFnBoWAMm5cykdynDXDU7uWDj4rTjxO1ToHTL9pkzR_K3o5CYpVE0ECC16q5Tw",
  "token_type": "bearer",
  "expires_in": 1209599
}

Each successful token migration request will return an access token and a refresh token that can be used in API V2 on behalf of the user who owns the API V1 refresh token you migrated. API V2 access tokens are also accepted when authenticating requests to API V1.

You will need to use the token migration endpoint to migrate each API V1 refresh token your integration holds on behalf of your users.

You can also choose not to migrate API V1 tokens — in that case, every user of your integration will need to go through the API V2 OAuth2 authorization flow when your integration starts using API V2.

Migrating Integrations Using XML Requests

API V2 doesn’t support XML request payloads nor XML responses. You will need to change your integration to use JSON in request payloads, and to process JSON responses from API V2.

Required Headers

Requests sent to API V2 must include these headers:

• User-Agent: the value can be set to any User-Agent string which correctly identifies your integration. It cannot be empty.
• Harvest-Account-Id: The value must be set to a valid ID of a Harvest account. If you’re using a Personal Access Token, you can get the IDs of your Harvest accounts by clicking on your personal token in the Developers section of Harvest ID. If your integration uses OAuth2 access tokens, you can get a list of the accounts that an access token can access through the Accounts endpoint.

Pagination

API V2 supports pagination in all of its endpoints. The default page size is 100 records. Endpoints in the Reports API have a default page size of 1000 records.

Unsupported API V1 Libraries

These libraries we recommended for API V1 don’t seem to offer support for API V2. We suggest contacting the owners of these libraries for further information:

• Ruby: Harvested, by Zach Moazeni.
• Python: Harvest Time Tracking API Client, by Lionheart Software.
• Java: Harvest Time Tracker Console Client, by Mauricio Offermann.
• Java: Harvest Java Wrapper, by Dag Martin Mikkelsen.
• PHP: HaPi - PHP Harvest API, by Matthew Denton.
• Drupal: Harvest Module for Drupal, by ImageX Media.
• .Net: Harvest.Net, by Joel Potter.
• Swift: HarvestKit, by Matt Cheetham.
• Elm: harvest-api, by comSysto.
• PHP harvest-api, by best it.

Resources

• API V2 Overview
• API V2 Authentication
• API V2 Pagination