LinkGuideReference

Integrating Hoseki Connect UI

IntroductionCopied!

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 to integrate and utilize the Hoseki Connect UI in your application.

OverviewCopied!

The Hoseki Connect UI process involves the following steps:

  1. Creating a session.

  2. Redirecting the user to the Hoseki Connect UI.

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

  3.  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 IntegrationCopied!

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/connect/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 financial standings, including available and current funds, and overall account value across different currencies or assets

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

  • addresses: permission to view the account's associated cryptocurrency addresses (if applicable to the account type).

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 digital asset accounts.

The user will now see the above screen and proceed to authenticate wherever their digital assets are stored. Each time a user makes one of these connections, 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. 

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

    2. If status is abandoned, it means Hoseki Connect UI initialization resulted in an error or the user exited the flow.

      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.

  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.

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/__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 URLCopied!

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/

API AuthenticationCopied!

Ensure all API requests are authenticated using bearer tokens and are made over HTTPS.

Example:

curl -X GET https://api.hoseki.app/v1/connect/sessions/sn_8N2cX3N0NH3SfQvqmEb75 \
-H "Authorization: Bearer <your API key>"

By following these steps, you can integrate the Hoseki Connect UI into your application, enabling your users to connect their digital asset accounts securely. For any issues or further assistance, refer to the API documentation or contact the Hoseki support team.

Copyright © 2024 Hoseki