In order to make calls to protected API resources, you will need to authenticate yourself to our servers. If you're using our handy PHP helper class, simply specify your API Key and Signature in class instantiation to authenticate and you're done. If you're making your API call from a language other than PHP, via Curl, or via other means, you will need to provide hashed credentials for the call to go through.
Authentication is done via Basic HTTP Auth and our API will expect to receive an Authorization header with appropriate credentials:
Authorization: BASIC < credentials >
All API calls should be made over HTTPS to ensure additional security.
< Credentials > consist of Username/Password pair encoded using base64. For more information on basic authentication, please refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication or search the web.
You will use your API Key and Hash in the Username and Password fields respectively. A hash is generated based on your API signature and request details. Complete explanation of how to produce the hash is found below.
For the walkthrough below, we will use this sample request to illustrate the process step by step. Let's assume we're making a GET request to obtain all upcoming events for a certain company.
API call: /events/company/
API URL: https://api.myeventguru.com/1
companyId = 123456789
type = "active"
timestamp = provide current Unix timestamp --> mandatory on ALL requests
Your API KEY: 123MySecretAPIKEY456
Your Signature: 978HowSecret!RandomChars321
Step 1. Produce an uppercase string representing HTTP request method (GET, PUT,POST, DELETE):
Step 2. Produce a fully normalized URL of the request including scheme and ports (if not 80 or 443)
Step 3. Build a parameter string with URL-encoded key/value pairs. For each parameter, the name is separated from the corresponding value by a '=' character (ASCII code 61). Each name-value pair is separated by an ampersand '&' character (ASCII code 38). String format: param1=value¶m2=value
Each key and each value must be URL encoded separately to comply with RFC3986 and then put together into the format specified above.
NOTE: Don't forget to include mandatory 'timestamp' parameter in your request. It is excluded in the example above because the value would obviously change, and we wanted you to be able to follow our calculations
Step 4. Create a base string. URL-encode the output of each step from 1-3 and concatenate together in order (#1 first, #2 second, and #3 last) using ampersand '&' character (ASCII code 38)
Step 5. Create a URL-encoded value of your API signature according to RFC3986
Step 6. Generate a keyed hash value using the HMAC method
a. Input string to encrypt should be the output from Step 4
b. The key used to encrypt it should the output from Step 5 (your URl-encoded API signature)
c. SHA256 algorithm should be used
d. Output should be raw binary data
NOTE: the result shown above is a lowercase hexit version of the raw binary data NOT the actual raw binary data
Step 7. Put together the username and password in "username:password" format where username is the API key and password is the output result from #6. Strip null characters (\0) from the string
This result should be base64 encoded and passed into the < Credentials > section of Authorization header