> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Third-party app

> Build a third-party app that connects to multiple Hyperline accounts via OAuth, with scoped permissions and secure token-based authorization.

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.

The Hyperline API supports the Authorization Code Grant flow ([RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)). This flow allows your application to get separate access tokens for each connected Hyperline account.

Use a well-established library for making OAuth requests. See the [OAuth library recommendations](https://oauth.net/code/).

## Registering your app

### Prerequisites

Hyperline enables third-party app creation manually. Contact the Hyperline team via the in-app chat to enable it.

### Creating an app

The first thing you need to do is [create a new app](/api-reference/endpoints/third-party-apps/create-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 the Hyperline API.

## OAuth flow

<Steps>
  <Step title="Authorize">
    To initiate the flow, you need to direct your user to [`https://api.hyperline.co/v1/oauth/authorize`](/api-reference/endpoints/oauth2/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](https://auth0.com/docs/secure/attack-protection/state-parameters))

    This endpoint redirects the user to the Hyperline login page.
  </Step>

  <Step title="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`](/api-reference/endpoints/oauth2/generate-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:

    ```json Response JSON body theme={null}
    {
      "access_token": "<token>",
      "refresh_token": "<token>",
      "expires_in": 3600,
      "token_type": "bearer"
    }
    ```
  </Step>

  <Step title="Use tokens">
    You must provide access tokens with every API call, specified in the `Authorization` header after a Bearer prefix. For example:

    ```sh API call using cURL theme={null}
    curl -H "Authorization: Bearer <access token>" https://api.hyperline.co/v1/customers
    ```
  </Step>
</Steps>

### 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`](/api-reference/endpoints/oauth2/generate-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`](/api-reference/endpoints/oauth2/revoke-token) (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

<Note>
  Learn about [multiple accounts](/docs/getting-started/sandbox#multiple-accounts) on Hyperline.
</Note>

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`](/api-reference/endpoints/companies/list-companies) endpoint.

To target a specific company, include the `Hyperline-CompanyId` header in each API request.

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

  Include this header by default when constructing a third-party app/flow.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.