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
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
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_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
firstname.lastname@example.org with password
foobar would use the following header:
email@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 51efffb9eb596a2c2cb17aee:9b9b8cfd45d32e5153e7deecfee7fc44 // base64 encoded: NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0 // formatted as HTTP Authorization header Authorization: Basic NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0
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.