API Authentication
The authentication method changed to JSON Web Tokens (JWT for short). The authentication should
be sent in the Authorization
HTTP header for every call.
JSON Web Tokens
JWT are a standardized (RFC7519) and open way for two parties to share authentication information securely. We are using the HMAC-256 algorithm for secure signatures.
JWTs are made up from three parts separated by dots (.
). The first is the header, the
second is the payload and finally the signature. Before encoding the following are
JSON objects.
- Header contains (usually) two parts:
alg
which should be the algorithm used for the signature,HS256
in our casetyp
this should beJWT
- Payload contains the claims we authenticate with the signature:
sub
: The user public key (Subject)iat
: Issued At, the UNIX timestamp when the signature was createdexp
: Expiry, UNIX timestamp when the signature will expireiss
: Issuer, the origin URIjti
: Unique token ID, MD5 of the concatenatedsub
andiat
Never set the expiry to be more than half a minute, tokens that are set for long expire time might be vulnerable to replay attacks.
Both of the above are Base64Url encoded, which form the first two parts of the token. The last part of the token is the signature, which is made using the two Base64Url encoded parts of the signature separated with a dot and signed with the chosen algorithm (HMAC-SHA256 in our case) with the user's private key.
Much more information and client libraries for almost all programming languages can be found on the following links:
- http://jwt.io/
- https://auth0.com/learn/json-web-tokens
We recommend that you make yourself familiar with JWT before using our API.
Example header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmMWI3YzhkZDM0YTkwYzFkMzI4MDgyMTQ2NzJiY2QyZSIsImlhdCI6MTQ0NzkyOTU0OCwiZXhwIjoxNDQ3OTI5NTQ4fQ.2frxLVGY4QDnB7mG1XWnWvAM36LSU58nocU1Ws5Sjzo
Important: In the earlier editions we made a typo calling the Bearer text as "Beamer", the API will work with both texts!
Note: The header value always starts with the text Bearer followed by a space and then the JWT
Server time
There can be a time difference between your server and ours. If you get errors messages saying that the signature is expired, you should check both times, and adjust your iat
and exp
parameters accordingly. You can use the leeway
parameter in the official PHP library.
You can also check the Billingo server time at the following URL:
or to get the data in a JSON format:
https://www.billingo.hu/time?type=json
Both of these endpoints are available without authentication