Welcome to our Dev Docs!

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:

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.

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_idand 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.

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).

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