Privileged API Keys Only
Special permission is required to access this service. Please contact api-support@sparkplatform.com or your API key provider to request access to this data.

Developers: Keys

API keys allow developers to access data via Spark API. Keys are always associated with a developer identity.

  1. Supported Roles
  2. Available Services
    1. All Developer Keys
    2. Individual Developer Key
  3. Developer Key Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes Notes
IDX No No
Public No No
VOW No No
Portal No No
Private Yes Yes Only accessible by MLS and association users, and by API keys granted explicit permission.
More information about roles may be found here.

Available Services

All Developer Keys

URI: /<API Version>/developers/identities/<Identity.Id>/keys

HTTP Method Description Conditional Notes
GET Returns all keys for an identity No
POST Creates a new API key No The Secret attribute is only returned as a response from this request.
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

GET Request

Parameters:
Parameter Required Notes
Pagination No

GET Response

{
    "D": {
        "Success": true,
        "Results": [
          {
            "Id": 5,
            "ResourceUri": "/vX/developers/identities/101/keys/5",
            "Type": "OAuth2",
            "Name": "My Application",
            "Key": "...",
            "RedirectUri: "https://sparkplatform.com/callback",
            "ApplicationUri": "https://sparkplatform.com",
            "SingleSession": true,
            "Replication": false,
            "DataRole": "idx",
            "TemplateId": null,
            "Enabled": true,
            "Comments": null,
            "LastActive": "2012-03-07T21:13:11Z",
            "Editable": true,
            "ModificationTimestamp": "2014-06-27T10:01:06-05:00",
            "CreatedTimestamp": "2014-06-27T10:01:06-05:00"
          }
        ]
    }
}

POST Request

Request body: 
{
    "D": {
      "Name": "My Application",
      "RedirectUri: "https://sparkplatform.com/callback",
      "ApplicationUri": "https://sparkplatform.com",
      "SingleSession": true,
      "Replication": false,
      "DataRole": "idx"
    }
}

POST Response

{
    "D": {
        "Success": true,
        "Results": [
          {
            "Id": 6,
            "ResourceUri": "/vX/developers/identities/101/keys/6",
            "Type": "OAuth2",
            "Name": "My Application",
            "Key": "...",
            "Secret": "...",
            "RedirectUri: "https://sparkplatform.com/callback",
            "ApplicationUri": "https://sparkplatform.com",
            "SingleSession": true,
            "Replication": false,
            "DataRole": "idx",
            "TemplateId": null,
            "Enabled": true,
            "Comments": null,
            "LastActive": null,
            "Editable": true,
            "ModificationTimestamp": "2014-06-27T10:01:06-05:00",
            "CreatedTimestamp": "2014-06-27T10:01:06-05:00"
          }
        ]
    }
}

Individual Developer Key

URI: /<API Version>/developers/identities/<Identity.Id>/keys/<Key.Id>

HTTP Method Description Conditional Notes
GET Returns a specific API key No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Updates a key record. No
DELETE Deletes a key record. No

GET Request

Parameters:
  • None

GET Response

See the GET request section for for the identities service.

PUT Request

Request body: 
{
    "D": {
      "RedirectUri: "https://sparkplatform.com/callback",
    }
}

PUT Response

The standard success/fail response is returned.

DELETE Request

Parameters:
  • None

DELETE Response

The standard success/fail response is returned.

Developers: Key Description

Attribute Data Type Writeable Required Description
Id Integer No No The unique id for the key.
ResourceUri Character No No The URI to the individual key.
Name Character Yes Yes The name of the key, ideally an end-user friendly string that names the application using the key.
Type Character Yes Yes The type of key, which determines the authorization flow the key will use. Currently, only OAuth2 is supported for most keys, but privileged keys can also access SparkApiAuth keys.
Key Character No No The 'key', used for the authorization flow.
Secret Character No No The 'secret', used for the authorization flow.
For keys where the Type is OAuth2, the secret is only obtainable immediately after creation and cannot be manually set.
RedirectUri Character OAuth2 keys only Yes Specific to the OAuth 2 keys, specifies the callback URI users are redirected to after they have granted the application access to their data.
ApplicationUri Character OAuth2 keys only Yes An end-user friendly URI linking to a website with information about the product the key is for.
MultipleMls Boolean OAuth2 keys only No If true, the key will have values in MlsIds and thus have access to the data in multiple MLSs.
Replication Boolean Yes No If true, the key will be granted access to Spark's data replication services.
SingleSession Boolean OAuth2 keys only No If true, the key will use a single-session, non-expiring access token, bound to a single user.
DataRole Character Yes Required if TemplateId is null. The data role under which the key will access data.
MlsIds Character List OAuth2 keys only No A list of MLSs the key will be able to access. Special permission is required to modify this value.
TemplateId Character OAuth2 keys only Required if DataRole is null. The template this key will use to define its role and other permissions.
Enabled Boolean Yes No If false, the key is disabled and cannot be used to access the API.
Comments Character OAuth2 keys only No Additional comments or notes regarding the API key.
LastActive Timestamp No No The last date and time the API key accessed Spark API. Note: this is only accurate to the day, as the timestamp is updated at most once per day.
Editable Boolean No No If true, the current user can modify the key record.
CreatedTimestamp Timestamp No No The time the key was created.
ModificationTimestamp Timestamp No No The time the key was last updated.
Websites Expansion OAuth2 keys only No
Uri Character OAuth2 keys only Yes The web address. Must be unique per key.
PermittedIPAddresses Expansion (Character List) OAuth2 keys only No A list of IP Addresses this key is restricted to. If empty or null, there is no restriction.
PermittedUserAgents Expansion (Character List) OAuth2 keys only No A list of allowed User-Agent values that must be set by requests made by this key. If empty or null, there is no restriction.

Expansions

Expansion Roles Single Record Only? Selection Support? Description
Websites All No No A list of websites either accessing data with the key or for the business that owns the key.
PermittedIPAddresses All No No See the documentation for this attribute under the response description.
PermittedUserAgents All No No See the documentation for this attribute under the response description.

API Explorer

The API Explorer does not currently support this service.