Hyperline supports the creation of external integrations, so your product can connect with any Hyperline account.

This capability allows external apps to build use-cases such as:

  • automating or white-labeling billing-specific needs
  • allowing your app to view the data of an Hyperline account
  • enabling your app to manage the customer base of an Hyperline account
  • allowing your app to manage the product catalog of an Hyperline account
  • allowing your app to manage recurring subscriptions or one-time payments of an Hyperline account
  • fetching invoices from an Hyperline account

This list is non-exhaustive and variety of flows can be built levering this kind of app.

​
Getting started

Hyperline uses OAuth standard to allow your app to access data from a connected account with the user consent. This prevents having to manually exchange API keys. For example, with the user’s consent, using OAuth you can call the subscription API on behalf of your user to create an Hyperline subscription.

Our API supports the Authorization Code Grant flow (RFC 6749 section 4.1), which allows your application to get separate access tokens for each connected Hyperline account.

We recommend using a well-established library for making OAuth requests. You can find some recommendations here.

​
Registering your app

The third-party app creation capability is granted manually by us. Please contact our support if you are interested and want to enable it.

The first thing you need to do is creating a new app in Hyperline using the Apps API. You will receive a Client ID and Client Secret, both of which should be kept secret. These credentials can be used to:

  1. Redirect users to your app’s authorization form (Client ID)
  2. Exchange auth codes for access tokens (Client ID & Client Secret)
  3. Renew your access tokens
  4. Deauthorize users from your app (Client ID & Client Secret)

Use the create new app API, including the following attributes in a JSON body:

  • name: displayed to the user during the authorization flow
  • description (optional): to show more details to the user
  • logo_uri (optional): to customise the authorization screen with your brand
  • callbacks: URLs whitelisted to use as a callback/redirect after authorization (e.g. an URL within your app that processes authorizations)

For now, apps can only be managed (listed, updated, deleted) using our API.

​
OAuth flow

1

Authorize

To initiate the flow, you need to direct your user to https://api.hyperline.co/v1/oauth/authorize (or https://sandbox.api.hyperline.co/v1/oauth/authorize). You must append these four query parameters to the URL:

  • client_id: received upon app registration
  • redirect_uri: where the user will be sent after authorization, it must match the URL you set when registering your app
  • response_type=code: the only supported mode at the moment
  • state: a random string to prevent CSRF attacks that you verify when the user returns to your app - more information

This endpoint will redirect the user to the Hyperline login page.

2

Retrieve tokens

After authorization, the user is redirected to your redirect_uri with the code and state query parameters. You must ensure that the query parameter state matches the original state you passed at the start of the flow.

If it does, you can exchange the provided code for tokens by making a POST request to https://api.hyperline.co/v1/oauth/tokens (https://sandbox.api.hyperline.co/v1/oauth/tokens), including the following attributes in a JSON body:

  • client_id: as above
  • client_secret: received upon app registration
  • grant_type: "authorization_code"
  • code: as provided in the query parameters
  • redirect_uri: must match the value set at the 1. Authorize step

You’ll then receive tokens in the JSON body:

Response JSON body
{
  "access_token": "<token>",
  "refresh_token": "<token>",
  "expires_in": 3600,
  "token_type": "bearer"
}
3

Use tokens

Access tokens must be provided with every API call, specified in the Authorization header after a Bearer prefix. For example:

API call using cURL
curl -H "Authorization: Bearer <access token>" https://api.hyperline.co/v1/customers

​
Tokens expiration

Access tokens are time limited — you need to refresh them periodically using the refresh token. The time limits are listed below.

  • Access token: 24h
  • Refresh token: does not expire automatically (can be revoked)

You can use the expires_in field to know the number of seconds left before the app access token expires. Be sure to renew it before this reaches zero.

​
Managing tokens

​
Refresh a token

If you wish to renew an access token, you can make a POST request to https://api.hyperline.co/v1/oauth/tokens (or https://sandbox.api.hyperline.co/v1/oauth/tokens), including the following attributes in a JSON body:

  • client_id: received upon app registration
  • client_secret: received upon app registration
  • grant_type: "refresh_token"
  • refresh_token: received during the first authorization flow

​
Revoke a token

Once issued, access tokens cannot be revoked in the same way as cookies with session IDs for server-side sessions. As a result, tokens should be refreshed periodically if the user remains active.

You can revoke refresh tokens in case they become compromised. Simply make a POST request to https://api.hyperline.co/v1/oauth/revoke (or https://sandbox.api.hyperline.co/v1/oauth/revoke), including the following attributes in a JSON body:

  • client_id: received upon app registration
  • client_secret: received upon app registration
  • token: refresh token you want to revoke

​
Multiple accounts

Learn about multiple accounts on Hyperline.

Each access token grants access to all companies associated with the user. To retrieve a list of all user-accessible companies, utilize the https://api.hyperline.co/v1/companies endpoint.

For targeting a particular company, include the Hyperline-CompanyId header in each API request.

If a user has access to multiple companies and you don’t specify the Hyperline-CompanyId header, the first company (oldest one) linked to the user will be used.

We advise including this header by default when constructing a third-party app/flow.

React componentsWebhooks