Authentication

Interactive Swagger Usage & Authentication

This documentation is interactive, allowing you to test and see first-hand how our system operates. To utilize these interactive features:

1. Acquire a bearer token for your active billwerk sandbox account. The procedure for this is outlined here.

2. Use the OAuth token URL:

   • Sandbox: https://sandbox.billwerk.com/oauth/token/
   • Production: https://app.billwerk.com/oauth/token/

   Note: The URL does not include [...]/api/v1/[...].

3. After obtaining the token, proceed to the 'Authorize' form below (highlighted by a green button). This will enable interactive features.

Caution: Testing the endpoints will affect your sandbox account!

Introduction

The REST API utilizes 2-legged OAuth, adhering to the OAuth 2.0 specification. Essentially, it enables you to obtain an access token by providing a username and a password (or a client id and client secret, respectively). Following this step, only the access token is used to authorize requests, replacing the username/password pair. This simple indirection comes with several advantages as it is standardized, extensible, and circumvents the need for excessive computationally expensive password hashing. The tokens are not self-validated. Given the stateless nature of calls, the token must be included in every request, either within an HTTP Authentication header or as a parameter:

As an HTTP header:

curl -H "Authorization: Bearer OAUTH-TOKEN" https://app.billwerk.com/api/v1/...

As a parameter:

curl https://app.billwerk.com/api/v1/...?access_token=OAUTH-TOKEN

Acquiring Access Tokens

Billwerk+ Transform supports two 2-legged OAuth grants at this time: The 'Resource Owner Password Credentials Grant' and the 'Client Credentials Grant'.

Client Credentials Grant

A 'confidential' OAuth client is a client able to store its credentials (typically a web application) securely. Such clients possess a client_id and a client_secret, which can be used to retrieve an access token directly. This is the recommended approach if you wish to query the Billwerk+ Transform API in response to webhooks or otherwise connect your web-based application to Billwerk+ Transform, as it decouples your API from your frontend login and operates outside any user context. OAuth clients can be created in your account under Settings/My Apps. When you create a confidential client, it will have both a client_id and a client_secret which can be used to retrieve an access token in this manner.

Resource Owner Password Credentials Grant

This grant necessitates the user to provide their username and password to you. This comes with the usual drawbacks of password-based authentication: the requirement to store the password securely and a password change will render your backend inoperable. However, this flow can be utilized from, for instance, mobile applications, desktop applications, and other frontends that cannot securely store a client_secret. Such applications are termed 'public' OAuth clients.

🚧

Client credentials

To connect your backend, it's advisable to use the client credentials grant so you don't have to store your Billwerk+ Transform access password in your database. For each client system, create its own client credentials in the Billwerk+ Transform settings. Avoid using the credentials of the Billwerk+ Transform Admin UI! However, ensure not to rely on the currently infinite lifetime of the access token.

📘

Access tokens

OAuth clients should be capable of re-requesting access tokens. They must not retrieve a new access token with every request, to avoid reaching request limits swiftly. The URL to acquire the OAuth token is https://{system}.billwerk.com/oauth/token where {system} can be app (for the production system) or sandbox (for the sandbox system).

Acquiring Access Tokens via Client Credentials Grant

POST /oauth/token/
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

grant_type=client_credentials

Here, the Basic authorization consists of the client_id and client_secret. Please note that client_id must not be specified in the request body because it's already contained in the Basic authorization header.

Acquiring Access Tokens via Resource Owner Password Credentials Grant

POST /oauth/token/
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=YOUR-USER-NAME&password=YOUR-PASSWORD&client_id=YOUR-CLIENT-ID 

Please note that username is the e-mail address of a Billwerk+ Transform user, password is the user's password, and client_id is the id of your app which must be registered with Billwerk+ Transform before use. Hence, the password grant_type requires the user to share their password with you (2-legged OAuth).

Notes on HTTP Basic Authorization

HTTP Basic Authorization headers are Base64-encoded strings following the scheme username:password. For instance, a user [email protected] with password foobar would use the following header:

[email protected]:foobar                               | Concatenated username and password
am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy                      | Base64 encoded
Authorization: Basic am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy | HTTP Header

In the client credentials grant, this boils down to client_id:client_secret, e.g.:

// client_id:client_secret
51efffb9eb596a2c2cb17aee:9b9b8cfd45d32e5153e7deecfee7fc44

// base64 encoded:
NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0

// formatted as HTTP Authorization header
Authorization: Basic NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0

3-legged OAuth

Further grant_types, specifically, those required in 3-legged OAuth (3LO) where the user doesn't have to share his credentials with 3rd parties, are planned for future implementation.