API Reference

Authenticating with Hover's API

This guide will demonstrate how to use your API credentials to generate an access token and use that access token to make API requests to Hover.

Before You Start

In order to make API requests to Hover, you will need a set of API credentials (Client ID and Client Secret). If you have not generated these credentials with Hover, please go to the previous page, and follow the tutorial to create a Hover integration and secure your credentials. You will need the following values before you can begin the authentication process:

  • Client ID
  • Client Secret
  • Redirect URI

Understanding the Authorization Code Grant Type flow

The OAuth 2.0 Authorization Code Grant Type flow consists of the following steps. We will delve deeper into each step of this process, but here is the high level overview on how to authenticate with this flow:

  • User Authentication: The client application (your integration) redirects the user to the authorization server for authentication and consent.
  • User Consent: The user provides consent to the client application, granting it permission to access their resources.
  • Authorization Code: After consent is granted, the authorization server returns an authorization code to the client based on the redirect URI value
  • Token Exchange: The client application exchanges the authorization code for an access token and a refresh token.

Obtaining an Authorization Code

The first step in this flow is to obtain an authorization code. It's recommended that this request routes to a browser, or your integration needs to make a GET request to the /oauth/authorize endpoint with the following query parameters:

  • Client ID -- your application's Client ID
  • Redirect URI -- your application's redirect URI, the place you want user's to land after allowing the integrating; the redirect must be secure, meaning begin with https (For testing, you can use https://hover.to).
  • response_type-- the value should be hardcoded to code for this request to work

Here's a sample request URL:

https://hover.to/oauth/authorize?response_type=code&redirect_uri=https://hover.to&client_id=123456789

If you paste a version of the above URL into a browser with your organizations credentials, you can try this step manually.

A user of your integration will be sent to Hover to log in with their email/password credentials and grant your integration access to the organization in Hover that they belong to.

Clicking Allow means the integration is allowed to retrieve your organizations data in Hover. After a user grants app authorization (by clicking the Allow button), the authorization server will redirect the user back to the configured redirect_uri with the authorization code appended to the end as a query parameter. It will look like the following, where everything after code= is the authorization code you need.

https://hover.to/?code=_<123ThisIsTheCode123>_

You can now save that authorization code value for the next step.

For more information on obtaining an authorization code, please refer to our reference documentation for more details on this request.

Exchanging the Authorization Code for API Tokens

Now that you've successfully obtained an authorization code, we can make a POST request to the /oauth/token endpoint to obtain your access token and refresh token. These tokens are what will allow you to be authenticated to use the API, and make successful requests.

Note: It is recommended that you send these parameters as body parameters with the content-type set to either multipart/form-data or application/json.

  • client_id -- your application's Client ID value (learn more about where to find this here)
  • client_secret -- your application's Client Secret value (learn more about where to find this here)
  • redirect_uri -- your application's redirect URI value
  • grant_type -- set to the string value of authorization_code
  • code -- this value is the authorization code obtained in the previous step

Refreshing your API Tokens

An access token is valid for 2 hours and will need to be refreshed in order for subsequent API requests to Hover to work. This is the same API request to obtain the initial access token, but with slightly different parameters:

  • client_id -- your application's Client ID value
  • client_secret -- your application's Client Secret value
  • redirect_uri -- your application's redirect URI value
  • grant_type -- set to the string value of refresh_token to indicate to Hover that you are refreshing your token
  • refresh_token -- this value should be your most recently-retrieved refresh token.

A successful request will yield a fresh pair of access/refresh tokens.

For more information on obtaining an access token or refreshing a token, please see our Authentication documentation.

Frequently Asked Questions

Can I automate the user authentication/consent process?

No -- in order to generate an authorization code, a user mustmanually allow the integration access to Hover's data on that user's behalf. Once the initial authorization code has been generated and exchanged for an access token and a refresh token, you can use the refresh tokens to generate new access tokens indefinitely. In other words, it's possible that a user only has to grant application authorization one time.

How long are access tokens and refresh tokens valid for?

An access token is valid for 2 hours. A refresh token is valid indefinitely, but invalidates when it is exchanged for a new access token/refresh token combination.

I am receiving a 401 Unauthorized error when trying to generate an access token or refresh my access token. What should I do?

A 401 Unauthorized error could mean a number of things went wrong. For example, you could've tried to use an invalid refresh token to obtain a new access token or you had a malformed body parameter. In the case of a 401, you should double-check all of the parameters you are passing into your API request. If there are no glaring errors, it is recommended that you start the authorization code flow from the beginning (generating a new authorization code and exchanging it for a new access token/refresh token combination).

Hover's API supports OAuth 2.0. This authorization framework enables application to obtain programmatic access to HTTP services and APIs. Specifically, Hover supports the OAuth 2.0 Authorization Code Grant Type

I am receiving the following message when trying to Allow my integration: "Third-party integrations are not available on your plan. Upgrade or contact us at (844)754-6837 or [email protected] to learn more."

This message means your org does not have integrations enabled. Please talk to your account manager to rectify this. Integrations must be enabled to proceed.