Introduction
The GMR sweepstakes API uses the HMAC-SHA-256 algorithm to verify data origin and integrity.
All authenticated requests must include a X-GmrSwps-Signature header. The value of the X-GmrSwps-Signature header will be the Base64-encoded HMAC-SHA-256 hash of the concatenation of the X-GmrSwps-User, X-GmrSwps-TimeStamp, X-GmrSwps-Nonce, X-GmrSwps-Protocol header values and the body of the request, in that order. The secret used by HMAC-SHA-256 algorithm to create the hash will be generated by GMR and securely shared with the client.
The following headers are required for successful authentication
| Name | Description |
|---|
| X-GmrSwps-User |
Must be the username provided to the client by GMR.
|
| X-GmrSwps-TimeStamp |
Must be the current Coordinated Universal Time and formatted according to ISO 8601 specifications. Example: 2021-04-21T18:40:49Z
|
| X-GmrSwps-Nonce |
A nonce generated by the client. This is a unique string that should be randomly/pseudo-randomly generated for each request. Suggested to be 32 characters or longer. Must be less than 255 characters
|
| X-GmrSwps-Protocol |
Must have the value of "HMAC-SHA-256". In the future, other values may be accepted.
|
| X-GmrSwps-Signature |
Must be the Base64 encoded hash of the concatenation of the above header values and the body of the request. At this time (as indicated by the X-GmrSwps-Protocol header) HMAC-SHA-256 must be the algorithm used.
|
The following shows an example of a call to "/api/v1/sweepstakes/entry" with the required headers, a request body, and the signature header that results. The secret used to calculate the signature in this example is
"7+Ln3AbS43qfGmZavx+Ve1nYZ2OrK/9k8I0Gy6CXMMPEkB4hCqeiU4PuAtGPi0ItoSWF1VOp1CDsu6QnjsJbsg==" as a Base64 encoded string, or,
"EF E2 E7 DC 06 D2 E3 7A 9F 1A 66 5A BF 1F 95 7B 59 D8 67 63 AB 2B FF 64 F0 8D 06 CB A0 97 30 C3 C4 90 1E 21 0A A7 A2 53 83 EE 02 D1 8F 8B 42 2D A1 25 85 D5 53 A9 D4 20 EC BB A4 27 8E C2 5B B2" as a string representation of the hexadecimal values.
The data that was hashed (header values + body) amounts to: GMRTest2021-04-16T15:00:00Zxxx123HMAC-SHA-256{ "ProgramId": "11111111-1111-1111-1111-111111111111"}
Sample Request:
POST https://{hostdomain}/api/v1/sweepstakes/entry HTTP/1.1
Content-Type: application/json
Host: {hostdomain}
X-GmrSwps-User: GMRTest
X-GmrSwps-TimeStamp: 2021-04-16T15:00:00Z
X-GmrSwps-Nonce: xxx123
X-GmrSwps-Protocol: HMAC-SHA-256
X-GmrSwps-Signature: v87p9hM+H1lnLrTGdvQC8o/z/Trc49/k1q7xQqrykEs=
{ "ProgramId": "11111111-1111-1111-1111-111111111111"}