Generating a Signed URL

When accessing the Koupon Media API, all calls must be signed so that Koupon Media can verify the caller has been authenticated and authorized to execute the command. Signing achieves the following objectives:

• Establishes the identity of the Client and the Application Type.
• Establishes trust in identifying the end consumer.
• Establishes scope/permissions and control over the caller.
• Allows for the end-to-end integrity of the request or transaction.

Every caller must have a unique “API Key” and an associated “Secret Key.” Contact your client success manager if you do not have an API key and Secret Key.

Note: Every call made to the v2 API’s must be made via this signed URL process. Any request without a valid authSignature will be rejected.

API Signature Process

Follow the steps below to generate a signed request.

In order to establish a secure communication between your service and the Koupon Media REST API, every method must be signed in the following way:

The steps below describe how to build a secure communication between your application and the “Register Consumer Identity” method. Note that no optional parameters are needed for the request.

1. Build the URL with any optional parameters

The “Register Consumer Identity” method (/consumer) registers a consumer’s device with the Koupon Media server using an HTTP POST request. No optional parameters are needed for the request, so the URL starts as:

http://consumer.kouponmedia.com/v2/consumer

2. Add your identifier and timestamp (Epoch/UNIX timestamp) to the URL

Note: any additional query parameters should be added to the URL before signing to include them in the signature. Any query parameters added after “authSignature” will not be included in the signature. Once we add the identifier and epoch timestamp to the URL, we get:

http://consumer.kouponmedia.com/v2/consumer?identifier=6348256714038520009a57d1d2-5188-457b-854b-86aafea65fc5&timestamp=1400606387

3. Encode the URL with your secret key

The following is a bash script that shows you how to use the SHA-1 algorithm to generate a secure hash of the request URL. You can use your languages built-in library to generate a SHA-1 hash.

echo -n "http://consumer.kouponmedia.com/v2/consumer?identifier=6348256714038520009a57d1d2-5188-457b-854b-86aafea65fc5&timestamp=1400606387" | openssl dgst -sha1 -hmac "4623B7B8-18A6-4B2C-B2C1-18157F5C4AFE"

4. Take the digest of the SHA-1 encrypted URL and use that value as the authSignature

The SHA-1 algorithm will result in the output of a hash that must be appended as the value of the authSignature.

http://consumer.kouponmedia.com/v2/consumer?identifier=6348256714038520009a57d1d2-5188-457b-854b-86aafea65fc5&timestamp=1400606387&authSignature=efe13eb5946fa208627142960352353efefd1d84

You can now use the resulting URL to make a successful call to the Koupon Media platform.

Additional headers

Accept header

Koupon Media API v2 returns results as JSON. Your requests should always include the header requesting the results as JSON:

Accept: application/json

 

Content-Type header

When sending data to Koupon Media in a POST or PUT request, your request must specify the content type of your request:

Content-Type: application/json; charset=utf-8

 

If your JSON request is invalid, the API will respond with a status code 400
Bad Request
. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.