Skip to main content
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 a Hyperline account
  • Enabling your app to manage the customer base of a Hyperline account
  • Allowing your app to manage the product catalog of a Hyperline account
  • Allowing your app to manage recurring subscriptions or one-time payments of a Hyperline account
  • Fetching invoices from a Hyperline account
This list is non-exhaustive, and you can build a variety of flows with this kind of app.

​
Getting started

Hyperline uses the OAuth standard to allow your app to access data from a connected account with the user’s 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 a 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

​
Prerequisites

Hyperline enables third-party app creation manually. Contact our support team to enable it.

​
Creating an app

The first thing you need to do is create a new app using the Apps API. You receive a Client ID and Client Secret. Keep both of them secret. You can use these credentials 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 customize the authorization screen with your brand
  • callbacks: URLs whitelisted to use as a callback/redirect after authorization (e.g. a URL within your app that processes authorizations)
For now, you can only manage apps (list, update, delete) 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 Hyperline sends the user 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 redirects the user to the Hyperline login page.
2

Retrieve tokens

After authorization, Hyperline redirects the user 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
3

Use tokens

You must provide access tokens with every API call, specified in the Authorization header after a Bearer prefix. For example:
API call using cURL

​
Token expiration

Access tokens are time-limited. You need to refresh them periodically using the refresh token. The time limits are:
  • 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

To renew an access token, 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, you can’t revoke access tokens in the same way as cookies with session IDs for server-side sessions. As a result, you should refresh tokens periodically if the user remains active. You can revoke refresh tokens in case they become compromised. 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, use the https://api.hyperline.co/v1/companies endpoint. To target a specific 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, Hyperline uses the first company (oldest one) linked to the user.We advise including this header by default when constructing a third-party app/flow.