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

Audience

This document is meant for:

Goals

Place orders via a private application, on behalf of users which don’t have a Bity account or don’t use their Bity account, in such a way that the following points are satisfied:

Definitions

Overview

The private application uses the OAuth Client Credentials grant to authenticate itself. To achieve the goals in a satisfactory manner, the application must be authenticated when estimating amounts, placing orders, duplicating orders, listing orders and accessing orders details.

The end user is not authenticated.

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 the Client-Id header is unnecessary.

Implementation details

Authentication with client credentials

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

The private application uses the Client Credentials Grant (RFC 6749 § 4.4) with one of the two most widely used authentication methods described below in order to obtain access tokens. It is recommended for the private application to use one of the already existing OAuth client libraries.

The private application needs to be configured with the following information in order to be able to obtain OAuth access tokens enabling to achieve the goals:

Additionally, the OAuth client library you choose might need to be informed of which authentication method to use if it supports more than one. Please consult its documentation in that regard.

Client secret in HTTP basic authentication

With HTTP basic authentication (RFC 7617), the request to the Token Endpoint look as follow:

POST /oauth2/token HTTP/1.1
Host: connect.bity.com
Authorization: Basic base64("OAuthClientId:OAuthClientSecret")
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https://auth.bity.com/scopes/exchange.client-history

base64("OAuthClientId:OAuthClientSecret") are the encoded secrets which in an actual request will look like QWxhZGRpbjpvcGVuIHNlc2FtZQ==.

An actual request will not have the extraneous new lines in the body which may have been inserted in this document during formatting.

Client secret in POST body

With the client secrets in the POST body, the request to the Token Endpoint look as follow:

POST /oauth2/token HTTP/1.1
Host: connect.bity.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https://auth.bity.com/scopes/exchange.client-history
&client_id=OAuthClientId&client_secret=OAuthClientSecret

OAuthClientId and OAuthClientSecret are an example, an actual request will have different values.

An actual request will not have the extraneous new lines in the body which may have been inserted in this document during formatting.

Requesting client credentials

To request the application credentials needed to achieve the goals, use the following form:

The authentication method you choose must match the authentication method used by the OAuth client library you choose.

Please submit the form to your point of contact at Bity.

Calling the Exchange API

When calling the Exchange API, the application must include a valid OAuth access token with the Bearer scheme 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.

For simplicity, ensure your private application always includes an Authorization header in the requests to the Exchange API.

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.

The following sections insist on the important details for achieving the goals.

Consulting order details and history, performing on-demand duplication

To achieve the first two goals, it is sufficient to ensure the Authorization header is present when performing the following operations:

For instance, a request for order details will look like the following example:

GET /v2/orders/87af11f3-b3cb-4683-a2f2-035ee0f86507 HTTP/1.1
Host: exchange.api.bity.com
Authorization: Bearer Ui3N9lDnaEFVNpQlWTa4mrn23AR0SDBGjEaRqyLF8lFuDnYsxZSAfw6gKa

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.