Authentication

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 support@ticketmatic.com. Please include:

  • a short description of why you would like api access
  • the account for which you request access

Authentication

There are two ways to authenticate using your API keypair:

  • Basic Auth
  • Request Signing

Basic Auth

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 <username>:<password> string.

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.

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 TM-HMAC-SHA256
  • accesskey
  • 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

Troubleshooting

If you are having trouble with the signing of API calls, try the following steps:

  1. Make sure your system clock is synchronized using NTP. This is a standard feature of every operating system.
  2. 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).
  3. Make sure you correctly concatenate the right hash parts and include all the needed information in the header.
  4. Check one of the provided API libraries for example code.
  5. If despite all of this you still have trouble connecting to the API: contact us, we’ll gladly help you investigate.