Third-party app
Enable your app to access Hyperline accounts using OAuth flows
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:
- Redirect users to your app’s authorization form (Client ID)
- Exchange auth codes for access tokens (Client ID & Client Secret)
- Renew your access tokens
- 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 flowdescription
(optional): to show more details to the userlogo_uri
(optional): to customise the authorization screen with your brandcallbacks
: 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
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 registrationredirect_uri
: where the user will be sent after authorization, it must match the URL you set when registering your appresponse_type=code
: the only supported mode at the momentstate
: 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.
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 aboveclient_secret
: received upon app registrationgrant_type: "authorization_code"
code
: as provided in the query parametersredirect_uri
: must match the value set at the1. Authorize
step
You’ll then receive tokens in the JSON body:
{
"access_token": "<token>",
"refresh_token": "<token>",
"expires_in": 3600,
"token_type": "bearer"
}
Use tokens
Access tokens must be provided with every API call, specified in the Authorization
header after a Bearer prefix. For example:
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 registrationclient_secret
: received upon app registrationgrant_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 registrationclient_secret
: received upon app registrationtoken
: 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.
Was this page helpful?