The OAuth 2.0 standard provides your users with a secure way to access Harvest data without providing sensitive information like usernames and passwords.
You'll need to register your application with Harvest (must be logged in as an administrator on your account to access this page) before using OAuth 2.0 for authorization. After registering, we'll provide you with credentials that your application can use to communicate with Harvest.
Please note: The OAuth 2.0 Sample App is a great starting point if you'd like to experiment with Harvest's OAuth 2.0 using your own registered client ID and secret.
Access tokens allow your application to communicate with Harvest on behalf of your users. Each user in Harvest is granted a token that expires after 18 hours.
Harvest uses the Authorization Code flow for server-side authorization.
-
Redirect users to Harvest to authorize their accounts with your application.
GET https://example.harvestapp.com/oauth2/authorize ? client_id=NMBEWl3h0r4KKNhfOsmPJw%3D%3D & redirect_uri=https%3A%2F%2Fexample.com%2Fredirect_path & state=optional-csrf-token & response_type=code
To limit access to a single Harvest account, you can specify its web address instead of api.harvestapp.com.
-
Get the authorization code when Harvest redirects back to your application. Harvest sends it to your redirect URI as a query parameter.
GET https://example.com/redirect_path ? code=Ao%2ByCqyGInOKuHVIMkwZGlk%2Nvq9Kt3eDGBpKvZnvWP4latLD6umv2dD76C100YbSABOEwUFqieosQRjNH7qvsA%3D%3D & state=optional-csrf-token
-
Request an access token using the authorization code.
Note: the
Content-Type
header for this request must beapplication/x-www-form-urlencoded
.POST https://example.harvestapp.com/oauth2/token
{ "code": "[authorization code from Harvest]", "client_id": "[your application's client ID]", "client_secret": "[your application's client secret]", "redirect_uri": "[your application's redirect URI]", "grant_type": "authorization_code" }
-
Get the access and refresh tokens from the response.
{ "token_type": "bearer", "expires_in": 64799, "access_token": "MDt6UyMCrY4h0tAQTxvynShtjddS64fyVcSYge2S7rSUT4vPy9Ny5TWa1sltXS2BjsF+uJgDKof+V2yQwdhI9Q==", "refresh_token": "GOk4bZ4bVcP4nqo071H9qxbX+c+UtLa1jMB7q1lpc1Y9/Me9GHlsQr8zm1VNSlS7lgm/DKjXdgFlwgj2WI6zCg==" }
-
Use the access token to send authorized requests to the Harvest API.
Note: the
Content-Type
andAccept
headers for this request must beapplication/json
orapplication/xml
.GET https://example.harvestapp.com/account/who_am_i ? access_token=Jjv5cUAnQx7R9jEECHNRxan7iMprt0ySncJhDdzQbtc%2FQXhMZcNVPQtJuBiDajPqNUz79o7S0FNvWc2WwIDcMA%3D%3D
-
Request a new access token after 18 hours using the refresh token.
Note: the
Content-Type
header for this request must beapplication/x-www-form-urlencoded
.POST https://example.harvestapp.com/oauth2/token
{ "refresh_token": "[user's refresh token]", "client_id": "[your application's client ID]", "client_secret": "[your application's client secret]", "grant_type": "refresh_token" }
-
Get the new tokens from the response.
{ "token_type": "bearer", "expires_in": 64799, "access_token": "ZWg6ru2KFzWv/fT9emMRlIvhADN85OWjeIKLdXZwlMZ7YUvgyVjdJZN8f2ydIfJhNhrJPBGvOtxYd3lHkvTWZg==", "refresh_token": "dwxM/Cf8E1mkiWtKHQEk7qEW4vXGzUH/JBm5Sra4Bnn6KVcGaqy6D7QipGe3OhelK66lYPnjLFSKc5BMvEVjRw==" }
Harvest uses the Implicit Grant flow for client-side authorization.
-
Redirect users to Harvest to authorize their accounts with your application.
GET https://example.harvestapp.com/oauth2/authorize ? client_id=NMBEWl3h0r4KKNhfOsmPJw%3D%3D & redirect_uri=https%3A%2F%2Fexample.com%2Fredirect_path & state=optional-csrf-token & response_type=token
To limit access to a single Harvest account, you can specify its web address instead of api.harvestapp.com.
-
Get the access token when Harvest redirects back to your application. Harvest sends it to your redirect URI as a hash parameter.
GET https://example.com/redirect_path # access_token=Ao%2ByCqyGInOKuHVIMkwZGlk%2Fvq9Kt3eDGBpKvZnvWP4latLD6umv2dT76C100YbSABOEwUFqieosQRjNH7qvsA%3D%3D & expires_in=64799 & state=optional-csrf-token & token_type=bearer
-
Use the access token to send authorized requests to the Harvest API.
Note: the
Content-Type
andAccept
headers for this request must beapplication/json
orapplication/xml
.GET https://example.harvestapp.com/account/who_am_i ? access_token=Jjv5cUAnQx7R9jEECHNRxan7iMprt0ySncJhDdzQbtc%2FQXhMZcNVPQtJuBiDajPqNUz79o7S0FNvWc2WwIDcMA%3D%3D