GuidesAPI Reference

Integrating Hoseki Connect UI

The Hoseki Connect UI is an interface that allows end-users to authenticate and grant access to their financial information. This guide provides a step-by-step process for integrating and utilizing the Hoseki Connect UI in your application.

Overview

The Hoseki Connect UI process involves the following steps:

  1. Creating a session.

  2. Redirecting the user to the Hoseki Connect UI.

  3. This is where Hoseki Connect UI will handle user authentication via third-party services like Coinbase or self-custody wallets like Bitcoin.

    a. Handling results and redirecting users back to the client application.

  4. Polling for Session Status

  5. (Optional) If you immediately need transactions or balance data, you will need to trigger ‘Account Refresh’

Step-by-Step Integration

1. Creating a Session

To start the authentication flow, you need to create a session. To do this, send a POST request to the /v1/connect/sessions endpoint.

To create a session, you must have a valid account_holder. An account_holder represents the user that will connect an account in the upcoming session. You can use an existing account_holder or to create a new one, you can use our Create An Account Holder API — POST v1/account_holders/. For more information on Account Holders and how they are represented in our object model, please review here.

Session Permissions

You must specify the data you wish to access using the permissions parameter on session creation. The current permission types are:

  • balances: permission to access and view the account's current balances, including available and current funds, and overall account value across different currencies or assets.

  • transactions: permission to retrieve the account's transaction history

Note: The addresses permission has been deprecated and removed with the introduction of our Verify APIs. Connect can no longer be used to link self-custodial addresses — it now only supports exchange or other custodial accounts.
Note: The user will see a disclaimer of the requested permissions during the connection flow.

Request: 

curl --request POST \
  --url https://api.hoseki.app/v1/connect/sessions/ \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "permissions": [
    "balances"
  ],
  "account_holder": "ah_QxA2TVrF",
  "return_url": "https://example.com/app"
}'

Note: We will redirect the user to the URL specified in the return_url when the authentication flow succeeds or fails. It also allows custom URL schemes (e.g., myapp://example). You will find more details about that in the Handling Results and Returning User’s and Handling Redirect URL sections.

Response: 

{
  "id": "sn_YaojD7ZMkzxNiDITju6i1",
  "account_holder": "ah_QxA2TVrF",
  "client_secret": "cs_8N2cX3N0NH3SfQvqmEb75",
  "hosted_url": "https://connect.hoseki.app/cs_8N2cX3N0NH3SfQvqmEb75",
  "status": "open",
  "permissions": [
    "balances"
  ],
  "accounts": [],
  "return_url": "https://example.com/app"
}

Note: The response contains a unique URL where end-users should be redirected to start the authentication flow.

2. Redirecting the User to Hoseki Connect

To start the Hoseki Connect account connections, redirect the user to the hosted_url with the system-installed browser. This URL will guide the user through the authentication process for their exchange accounts.

Currently, only Coinbase is supported so when the URL is called the user will be immediately directed to connect their Coinbase account. More exchange support will come soon. Each time a user connects you will receive a unique id for that connection. We call these connections Accounts.

3. Handling Results and Returning User’s

Once the user finishes connecting their digital asset account, they will be redirected to the URL specified in the return_url. This is an optional field specified during session creation. If no return URL is provided, the user will see a message indicating they can close the browser tab when they are finished with the flow.

The session status field will be updated to completed or abandoned, depending on the result. You can detect this change in one of two ways:

  1. If you’ve set return_url, we will redirect the user to the URL provided on a successful completion. We will send this with minimal data for optimal security. Once you have received notification of completion, you can use the /v1/connect/sessions/:id endpoint to retrieve more specific information about that session.

    • If status is completed, an account_ids field will be present and populated with the IDs of the accounts collected as part of the session.
    • If status is abandoned, it means Hoseki Connect UI initialization resulted in an error or the user exited the flow.

  2. If you didn't add the optional return_url field, Hoseki Connect will not have anywhere to redirect the user after completion. In this case, you will need to poll the session status once you redirect the user to Hoseki Connect UI. Check the Polling for Session Status below for more details.

Note: In the event of a user action outside of our application (e.g., closing the browser), we may not always be able to redirect the user to the URL specified in return_url. In these cases, it is still useful to poll session status.

4. Polling for Session Status

You can poll the session status by periodically sending GET requests to the /v1/connect/sessions/:id endpoint. We recommend sending no more than two per second, as anything else could be subject to our rate limit.

Request: 

curl --request GET \
  --url https://api.hoseki.app/v1/connect/sessions/{session_id} \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response: 

{
  "id": "sn_YaojD7ZMkzxNiDITju6i1",
  "account_holder": "ah_QxA2TVrF",
  "client_secret": "cs_8N2cX3N0NH3SfQvqmEb75",
  "hosted_url": "https://connect.hoseki.app/cs_8N2cX3N0NH3SfQvqmEb75",
  "status": "completed",
  "permissions": [
    "balances"
  ],
  "accounts": [
    "acc_K8RocpLg"
  ],
  "return_url": "https://example.com/app"
}

5. (Optional) Account Refresh

Upon initial connection, full balance and transaction data are not retrieved. To obtain this data, you will need to trigger an 'Account Refresh.' Given the resource-intensive nature of these requests, balances and transaction details are refreshed on an 'on-demand' basis. Each time you need an up-to-date view of balances and transactions, you will need to trigger a refresh.

For full information on refreshing an account, please refer to the Refresh Account Data guide.

Handling Redirect URL

For mobile applications, configure your app to handle redirects using platform-specific methods.

iOS:

Android:

For more details about the security standards, you can review them here: https://www.oauth.com/oauth2-servers/redirect-uris/redirect-uris-native-apps/

Copyright © 2025 Hoseki