Spark API Authentication

If you are not sure which authentication method to use, please read the Overview page.
The Spark API authentication procedure is as follows:
  1. The developer API key is signed and sent to the authentication service over SSL.
  2. The authentication service responds with a session token.
  3. Each subsequent request to the API must include a token and be properly signed.
Session tokens are good for a maximum of 24 hours, and have an idle timeout of 1 hour. After the session token has expired, authentication must occur again. Only one session token may be active for any single API key at one time. Authentication is designed to require the use of a proxy service to avoid exposing the shared secret in a user’s browser.
Notes
  • Requests to the /session service must be made using HTTPS, but requests to other services may be made with HTTP or HTTPS.
  • Only one session token may be active for an API key at any time.

Session management (Spark API auth only)

URI: /<API Version>/session

Verb Outcome Notes
GET Returns HTTP 405 (Method Not Allowed) 
Extends the session for another timeout period
 Not implemented 
The GET response is the same as the POST response
POST Create a new session See parameters below
PUT Returns HTTP 405 (Method Not Allowed) Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) 
Terminates the current session immediately
 Not implemented 

Parameters for all requests

Parameter Required Notes
ApiKey Yes Your API key
ApiSig Yes Signature for this request, generated as described below

POST Request

To create a new session, POST to the following URI with an empty POST body, substituting the proper ApiKey and ApiSig parameters: 
https://sparkapi.com/v1/session?ApiKey=12345&ApiSig=2fde9e59147081ad4e39382e1f809710

Signature Generation

ApiSig, the signature for this request, is generated by creating an MD5 hexadecimal representation of the following string: 
[secret]ApiKey[key]
  • [secret] is the secret pass-phrase assigned to your key (without the brackets)
  • [key] is your API key, without the brackets
Example: Assume [secret] is 1234 and [key] is abcd . The string to be processed with MD5 would then be: 
1234ApiKeyabcd
The above string, when processed with MD5 will be: 
2fde9e59147081ad4e39382e1f809710

POST Response

If a new session is successfully created, the response payload will look like the following: 
{
  "D" : {
    Success: true,
    Results: [ {
      AuthToken: "xxxxx",
      Expires: "2010-10-30T15:49:01-05:00"
    }]
  }
}

Authenticated Requests (Spark API auth only)

Subsequent calls to the API after a session is created may be made with either HTTP or HTTPS and have a similar format: 
https://sparkapi.com/v1/contacts?AuthToken=1234&ApiSig=3ebbd149f28c69c19fa0f38d5bb4d14
In all authenticated calls to the system, AuthToken and ApiSig are required. Signatures for authenticated calls are generated by creating an MD5 hexadecimal representation of the following string: 
[secret]ApiKey[key]ServicePath[service_path]param1[param1]...paramN[paramN][POST data]
  • [secret] is the secret pass-phrase assigned to your key
  • [key] is your API key
  • [service_path] is the path to the service being requested. For example, if the request is to https://sparkapi.com/v1/contacts, the service path will be /v1/contacts.
  • [token] is your session token, returned from a successful authentication request
  • [param1]...[paramN] are all parameters sent with the request, in alphabetical order first by parameter name and then by parameter value. AuthToken will always be included in this parameter list for authenticated requests.
  • [POST data] If a POST request is made, the JSON data must be appended to the end of the string to sign.
Example: assume [secret] is 1234, [key] is abcd and full request is http://sparkapi.com/v1/contacts?AuthToken=9876&name=John+Contact&email=contact@fbsdata.com&phone=555-5555&group=IDX Lead. The string to be processed with MD5 would be as follows: 
1234ApiKeyabcdServicePath/v1/contactsAuthToken9876emailcontact@fbsdata.comgroupIDX LeadnameJohn Contactphone555-5555

Expiration of tokens (Spark API auth only)

Tokens have a maximum life of 1 day (24 hours). The token will also expire if more than 60 minutes pass since the last request. When a session expires, an HTTP 401 status code will be returned on any request to the API with the following payload: 
{
  "D": {
    "Success": false,
    "Message": "Session token has expired",
    "Code": 1020
  }
}
When the token expires, an authentication call must be made to retrieve a new token. The original request must then be subsequently repeated.