API Key and Signature

To use the Zerista API you need to have an application key. We use this key to authenticate your requests and track API usage. A single API key is associated with a Zerista account; therefore, you must first have a Zerista account to get an API key. A key consists of an integer id and a string signing key. For the examples in this section, we will use the key_id 123456 and the key SEFOaW5Wc0drbHM1Z3JoNw==

Password resets on API keys

As mentioned above, every API key is directly associated with a user account. If the user that is associated with the API key resets their password, the API key will immediately loose it’s permissions. Please contact Zerista if you require a password reset on the user account that is associated with your key. Note: this section is not applicable with User-Mimicking via Token Authentication.

Request Signing

Every API request must be signed. First, add your key_id to the request’s parameters.

[sourcecode language=”text” light=”true”]
user[first_name]=rufus&user[last_name]=kanarowski&user[mapbuzz_auth_attributes][email]=rufus@gmail.com&key_id=123456
[/sourcecode]

Next, you must generate the signing string and hash it with the MD5 algorithm (hexadecimal output) to generate the request’s signature. This is done with the following steps:

  1. Concatenate all the HTTP parameters in the form = keeping the GET and POST parameter lists separate.
  2. Sort the GET and POST key-value pair lists separately.
  3. Concatenate the GET and POST key-value lists together.
  4. Concatenate the signing key to the string. NOTE: This is to be done before any keys or values are URI encoded. For example, the open square bracket character ‘[‘ should not be encoded as ‘%5B’

The form of the signing string:

[sourcecode language=”text” light=”true”]
<key-value-pair> ::= <key>=<value>
<get-params> ::= <key-value-pair><key-value-pair>…
<post-params> ::= <key-value-pair><key-value-pair>…
<sigining-string> ::= <get-params><post-params><signing-key>
[/sourcecode]

Here is an example of a signing string:

[sourcecode language=”text” light=”true”]
key_id=123456user[first_name]=rufususer[last_name]=kanarowskiuser[mapbuzz_auth_attributes][email]=rufus@gmail.comSEFOaW5Wc0drbHM1Z3JoNw==
[/sourcecode]

After hashing with MD5, we get a signature like:

[sourcecode language=”text” light=”true”]
61bd2da638caba60ffb2ea89a08e3b8d
[/sourcecode]

Finally, add the signature to the request’s parameters, and your request is ready to be submitted:

[sourcecode language=”text” light=”true”]
POST /user?key_id=123456&sig=61bd2da638caba60ffb2ea
89a08e3b8d&user[first_name]=rufus&user[last_name]=kanarowski&user[mapbuzz_auth_attributes][email]=rufus@gmail.com
[/sourcecode]

Longer Test Example

Key id: 3, Key String: 5vucuk6NMjrDhkP6WBVHCA==

Initial request:

NOTE: The password field (user[mapbuzz_auth_attributes][password]) specified in the example below is an “optional” field. If you plan on passing a password as a parameter, please communicate with Zerista beforehand. Also, do NOT pass a password parameter while making a PUT request as it will update the user’s existing password on the system.

[sourcecode language=”text” light=”true”]
POST /user?format=atom&user[last_name]=Wellton&user[mapbuzz_auth_attributes][password]=my
password&user[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.com&user[mapbuzz_auth_attr
ibutes][email_confirmation]=sandrine@mapbuzz.com&user[first_name]=Sandrine&user[account_a
ttributes][account_name]=sandrine&key_id=3
[/sourcecode]

Signing String:

[sourcecode language=”text” light=”true”]
format=atomkey_id=3user[account_attributes][account_name]=sandrineuser[first_name]=Sandri
neuser[last_name]=Welltonuser[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.comuser[ma
pbuzz_auth_attributes][email_confirmation]=sandrine@mapbuzz.comuser[mapbuzz_auth_attribut
es][password]=mypassword5vucuk6NMjrDhkP6WBVHCA==
[/sourcecode]

Signature:

[sourcecode language=”text” light=”true”]
7c3dcce0a03120c0ec1b61fca95f0cf3
[/sourcecode]

Final Request:

[sourcecode language=”text” light=”true”]
POST /user?format=atom&user[last_name]=Wellton&user[mapbuzz_auth_attributes][password]=my
password&user[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.com&user[mapbuzz_auth_attr
ibutes][email_confirmation]=sandrine@mapbuzz.com&user[first_name]=Sandrine&user[account_a
ttributes][account_name]=sandrine&key_id=3&sig=7c3dcce0a03120c0ec1b61fca95f0cf3
[/sourcecode]

Signature Testing

You can test your signature algorithm by using this URL:

[sourcecode language=”text” light=”true” autolinks=”false”]
https://{your-subdomain}.zerista.com/signature_test
[/sourcecode]

You may GET, POST, or PUT to this URL. It will give you debugging feedback including the expected signing string and whether or not your signature is correct.

Pseudo Code for Generating Signatures

[sourcecode language=”text”]
signingKeyId := your signing key ID
signingKey := your string signing key
getParameters := HashTable of HTTP GET parameters
postParameters := HashTable of HTTP POST parameters

ADD KEY:"key_id" VALUE:signingKeyId TO getParameters

getStrings = NEW Array OF Strings
postStrings = NEW Array OF Strings

FOREACH key,value IN getParameters DO
IF value IS NOT BLANK DO
newString = key + "=" + value
ADD newString TO getStrings
END
END

FOREACH key,value IN postParameters DO
IF value IS NOT BLANK DO
newString = key + "=" + value
ADD newString TO postStrings
END
END

SORT getStrings
SORT postStrings

signingString = NEW String

FOR string IN getStrings DO
CONCATENATE string TO signingString
END

FOR string IN postStrings DO
CONCATENATE string TO signingString
END

CONCATENATE signingKey TO signingString

signature = MD5 OF signingString IN HEXIDECIMAL

ADD KEY:"sig" VALUE:signature TO getParameters

# You can now build your HTTP request from your hash tables of GET
# and POST parameters.
[/sourcecode]

Leave a Reply

Your email address will not be published.