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.

user[first_name]=rufus&user[last_name]=kanarowski&user[mapbuzz_auth_attributes][email]=rufus@gmail.com&key_id=123456

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:

<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>

Here is an example of a signing string:

key_id=123456user[first_name]=rufususer[last_name]=kanarowskiuser[mapbuzz_auth_attributes][email]=rufus@gmail.comSEFOaW5Wc0drbHM1Z3JoNw==

After hashing with MD5, we get a signature like:

61bd2da638caba60ffb2ea89a08e3b8d

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

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

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.

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

Signing String:

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==

Signature:

7c3dcce0a03120c0ec1b61fca95f0cf3

Final Request:

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

Signature Testing

You can test your signature algorithm by using this URL:

https://your-subdomain.zerista.com/signature_test

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

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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s