Technical guide for using the Exchange API v2 with a public application with end user authentication

Audience

This document is meant for:

Goals

Place orders via a public application, on behalf of users using their Bity account, in such a way that the following points are satisfied:

Definitions

Overview

The public application uses the OAuth Authorization Code grant with the PKCE mechanism in order to authenticate the user and obtain an access token. To achieve the goals in a satisfactory manner, the application must use an access token when performing any operation on behalf of a user such as estimating amount, and placing orders.

The additional fees deducted by Bity on behalf of the partner are gathered with the partner revenue coming from the profit-sharing scheme.

When an OAuth access token is used, the usage of cookies and the usage of the Client-Id header are unnecessary.

Implementation details

Authentication with the authorization code grant

The Exchange API expects OAuth access tokens to be located in the Authorization header with the Bearer scheme (RFC 6750).

Public applications are expected to use the Authorization Code grant (RFC 6749 § 4.1) with PKCE (RFC 7636). It is recommended for public applications to use an existing OAuth client library supporting this type of OAuth grant.

The public application needs to be configured with the following information in order to be able to obtain OAuth tokens:

It is important that you ensure that your OAuth client is using PKCE (RFC 7636).

The aforementioned values (identifier, etc.) are accessible in the OAuth clients management application (opens in a new window).

Registering your application

To obtain new application credentials needed to achieve the goals, use the dedicated application (opens in a new window) and select “Using Exchange API via public application, requiring user authentication” while registering an application.

Android and iOS applications

As smartphone applications do not run inside the user’s web browser, the following additional points must be respected:

For the specific case of Android and iOS applications, ensure the Authorization Request (RFC 6749 § 4.1.1) is opened in the web browser and not inside your application. In particular, request the platform to open the URL and do not use a Web View, frame or other embedding mechanism to place the Authorization Request.

Your application must register the Redirection URI as a Deep Link or App Link on Android and as an Universal Link on iOS in order to be able to receive the Authorization Response.

It is important that you ensure that your application is using PKCE (RFC 7636).

Calling the Exchange API

When calling the Exchange API, the application must include a valid OAuth access token with the Bearer scheme (RFC 6750) in the Authorization header in order to achieve the goals. Please note that authentication in the Exchange API is optional so one can not expect to obtain an immediate feedback if the Authorization header is missing. When the Authorization header is invalid, a 401 or 403 response will be returned and the WWW-Authenticate header will contain additional information.

To avoid issues, ensure your public application always includes an Authorization header in the requests to the Exchange API when acting on behalf of an user.

The documentation of the Exchange API endpoints is available on https://doc.bity.com/ as an OpenAPI Specification in YAML format and a rendered HTML version.

What is possible to perform on behalf of the user is limited by the user consent which is made visible to your application via the OAuth scope. Make sure your application work adequately even when the user did not grant the largest possible scope to your application. For instance, users may grant your application the possibility to place orders on their behalf but may not grant it the possibility to access the listing of previously placed orders. In such situation you are naturally expected to let the user place orders as listing previously placed orders is not necessary in order to successfully place and execute an order.

The following is an example amount estimation on behalf of a user. Note that in this specific case, the status of the account of the user is such that it is not required to provide information about the object paying such order placed by the user. If you forget to include the access token in such request you would also obtain a response but it would not be representative of the particular situation of the user.

POST /v2/orders/estimate HTTP/1.1
Host: exchange.api.bity.com
Authorization: Bearer uk4pe6eneib8xia6Ievaipae6suchieziekie3tu6aiT7oa7
Content-Type: application/json

{
  "input": {"currency": "ETH"},
  "output": {"currency": "CHF", "amount": "200"}
}

and the corresponding example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input" : {
    "amount" : "1.398165328416715000",
    "currency" : "ETH",
    "object_information_optional" : true
  },
  "output" : {
    "amount" : "200",
    "currency" : "CHF",
    "minimum_amount" : "7.13"
  },
  "price_breakdown" : {
    "customer_trading_fee" : {
      "amount" : "0.011094292471898504",
      "currency" : "ETH"
    }
  }
}

Specifying an additional fee

To specify an additional fee in a satisfactory manner, the same additional fee must be specified when estimating amounts and when placing the corresponding order. Additionally, your application must adequately inform the user of the additional fee.

How to do this is detailed in the Technical guide for specifying an additional fee.