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:

The developer API key is signed and sent to the authentication service over SSL.
The authentication service responds with a session token.
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 Returns the Standard Response Format

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:

{
  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

Where <Signature> is replaced with the signature you generated above, your final request would look like:

http://sparkapi.com/v1/contacts?AuthToken=9876&name=John+Contact&email=contact@fbsdata.com&phone=555-5555&group=IDX+Lead&ApiSig=<Signature>

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.