OAuth 2.0.md

OAuth 2.0 Authorization

The OAuth 2.0 standard provides your users with a secure way to access Harvest data without providing sensitive information like usernames and passwords.

Registering Your Application

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

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.

For Server-Side Applications

Harvest uses the Authorization Code flow for server-side authorization.

1. 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.

2. 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
   

3. Request an access token using the authorization code.

   Note: the Content-Type header for this request must be application/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"
   }

4. 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=="
   }

5. Use the access token to send authorized requests to the Harvest API.

   Note: the Content-Type and Accept headers for this request must be application/json or application/xml.

   GET https://example.harvestapp.com/account/who_am_i ?
       access_token=Jjv5cUAnQx7R9jEECHNRxan7iMprt0ySncJhDdzQbtc%2FQXhMZcNVPQtJuBiDajPqNUz79o7S0FNvWc2WwIDcMA%3D%3D
   

6. Request a new access token after 18 hours using the refresh token.

   Note: the Content-Type header for this request must be application/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"
   }

7. Get the new tokens from the response.

   {
     "token_type": "bearer",
     "expires_in": 64799,
     "access_token": "ZWg6ru2KFzWv/fT9emMRlIvhADN85OWjeIKLdXZwlMZ7YUvgyVjdJZN8f2ydIfJhNhrJPBGvOtxYd3lHkvTWZg==",
     "refresh_token": "dwxM/Cf8E1mkiWtKHQEk7qEW4vXGzUH/JBm5Sra4Bnn6KVcGaqy6D7QipGe3OhelK66lYPnjLFSKc5BMvEVjRw=="
   }

For Client-Side Applications

Harvest uses the Implicit Grant flow for client-side authorization.

1. 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.

2. 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
   

3. Use the access token to send authorized requests to the Harvest API.

   Note: the Content-Type and Accept headers for this request must be application/json or application/xml.

   GET https://example.harvestapp.com/account/who_am_i ?
       access_token=Jjv5cUAnQx7R9jEECHNRxan7iMprt0ySncJhDdzQbtc%2FQXhMZcNVPQtJuBiDajPqNUz79o7S0FNvWc2WwIDcMA%3D%3D