This document is meant for:
Place orders via a confidential 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:
The confidential 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.
The Exchange API expects OAuth access tokens to be located in the
Authorization header with the Bearer scheme (RFC 6750).
The confidential 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 confidential application to use one of the already existing OAuth client libraries.
The confidential application needs to be configured with the following information in order to be able to obtain OAuth access tokens enabling to achieve the goals:
https://connect.bity.com/oauth2/tokenhttps://connect.bity.com/oauth2/revokehttps://auth.bity.com/scopes/exchange.client-historyAdditionally, 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.
The aforementioned values (identifier, secret, etc.) are accessible in the OAuth clients management application (opens in a new window).
To obtain new application credentials needed to achieve the goals, use the dedicated application (opens in a new window) and select “Using the Exchange API via confidential application for unauthenticated services” while registering an application.
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.
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.
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 confidential 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.
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
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.