Almost all calls to the Ticketmatic API need to be authenticated. An authorization header needs to be added to each request.
You’ll need a set of API keys to construct this header. A keypair consists of:
- accesskey: this is a public key and is passed in each request
- secretkey: this is a private key and is never passed in requests. It is only used as the key to compute the signature and it should be kept secret
Obtaining API keys
To obtain API keys, you can send an e-mail to firstname.lastname@example.org. Please include:
- a short description of why you would like api access
- the account for which you request access
There are two ways to authenticate using your API keypair:
- Basic Auth
- Request Signing
Basic auth is the simplest model of authentication for the Ticketmatic API. To authenticate using basic auth, you send a username and password in each request to the API. This is done by adding an
Authorization header to your request. The Authorization header must start with Basic , followed by a Base64 encoded
You use you accesskey as username and your secretkey as password.
Basic auth is supported out of the box by most tools and libraries used to perform web requests. For example in curl you simply use the
-u parameter to specify the username:password:
curl -u '<accesskey>:<secretkey>' https://apps.ticketmatic.com/api/1/<accountname>/events
Basic auth is the simplest method to authenticate, but also a bit less secure as you pass your secretkey in each request. If you prefer a more secure authentication method, you can use Request signing.
Every request you make to the API must carry with it a http Authorization header, containing the authentication string.
The authentication string has following components:
- auth scheme: should be
- timestamp: this is an UTC time in ISO-8601 format, for instance
2014-09-23T17:23:00. The timestamp should not be older than 30 minutes, compared to Ticketmatic system time. If the timestamp is not valid, a http code 401 will be returned.
- signature: computed by hashing the accesskey, the account shortname and timestamp using the secretkey as hashing key.
The hashing algorithm used is HMAC-SHA256. In PHP you would generate the signature as follows:
1$signature = hash_hmac("sha256", $accesskey.$accountshortname.$timestamp, $secretkey);
These components should be concatenated as follows:
1TM-HMAC-SHA256 key=ACCESSKEY ts=TIMESTAMP sign=SIGNATURE
An example of a complete http Authorization header:
1Authorization: TM-HMAC-SHA256 key=242dda885ec6024f934a40c0 ts=2014-09-23T17:23:00 sign=c27dc92415cb20dca85fec44f31b60b522bc3c9e422cb24a35dfc8538a1ab570
If you are having trouble with the signing of API calls, try the following steps:
- Make sure your system clock is synchronized using NTP. This is a standard feature of every operating system.
- Use the diagnostic time call to retrieve the server time and compare it to the timestamp you calculated yourself. This call does not require an authorization header to be set. Note that UTC time is used. Being able to retrieve this call also proves that you can reach the Ticketmatic API servers (and thus eliminates any firewall / SSL concerns).
- Make sure you correctly concatenate the right hash parts and include all the needed information in the header.
- Check one of the provided API libraries for example code.
- If despite all of this you still have trouble connecting to the API: contact us, we’ll gladly help you investigate.