Authentication · Developer Docs

Introduction

The REST API uses 2-legged OAuth, which is part of the OAuth 2.0 specification. In principle, all it does is to allow you to retrieve an access token by providing a username and a password (or a client id and client secret, respectively). Subsequently, only this access token is used to authorize requests instead of the username/password pair. However, this simple indirection comes with a number of advantages, because it is standardized, extensible and avoids excessive computationally expensive password hashing. The tokens are not self-validated. Since calls are stateless, the token must be given in every request, either in 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 supports the two two-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 that is able to securely store its own credentials (typically a web application). Such clients have a client_id and a client_secret, which can be used to retrieve an access token directly. This is the recommended approach if you want to query the billwerk API in response to webhooks or otherwise connect your web-based application to billwerk, because it decouples your API from your own frontend login and it does not run in any kind of user context. You can create OAuth clients in your account under Settings/My Apps. If 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 way.

Resource Owner Password Credentials Grant requires the user to present user name and password to you. That comes with the usual drawbacks of password-based authentication: You need to store the password securely and a password change will render your backend inoperable. However, this flow can be used from e.g. mobile applications, desktop applications and other frontends that can't store a client_secret securely. Such applications are called 'public' OAuth clients.

To connect your backend, it is advisable to use the client credentials grant so you don't have to store your billwerk access password in your database. For each client system create its own client credentials in the billwerk settings. Do not use the one of the billwerk Admin UI! Please make sure, however, not to rely on the currently infinite lifetime of the access token.

OAuth clients must be able to re-request access tokens. OAuth clients must not retrieve a new access token with every request, otherwise they'll run into request limits very quickly.
URL to aquire the OAuth token is https://{system}.billwerk.com/oauth/token. {system} can be app (for production system) or sandbox (for 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 user, password is the user's password and client_id is the id of your app which must be registered with billwerk before use. Hence, the password grant_type requires the user to share his password with you (2-legged OAuth).

Notes on HTTP Basic Authorization

HTTP Basic Authorization headers are Base64-encoded strings of the scheme username:password. For example, a user john.doe@example.com with password foobar would use the following header:

john.doe@example.com: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.