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.
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. |
Available Services
All Developer Keys
/<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", "Roles": ["idx", "single_session"], "TemplateId": null, "Enabled": true, "Comments": null, "LastActive": "2012-03-07T21:13:11Z", "Editable": true, "Deleted": false, "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", "Roles": ["idx", "single_session"] } }
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", "Roles": ["idx", "single_session"], "TemplateId": null, "Enabled": true, "Comments": null, "LastActive": null, "Editable": true, "Deleted": false, "ModificationTimestamp": "2014-06-27T10:01:06-05:00", "CreatedTimestamp": "2014-06-27T10:01:06-05:00" } ] } }
Deleted Developer Keys
/<API Version>/developers/identities/<Identity.Id>/keys/deleted
For reporting and billing purposes, API keys are soft-deleted.
HTTP Method | Description | Conditional | Notes |
---|---|---|---|
GET | Returns all keys under an identity that have been deleted | No | |
POST | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
PUT | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
DELETE | Returns HTTP 405 (Method Not Allowed) | No | Not implemented |
GET Request
Parameters:- None
GET Response
See the GET request section for for the keys service.
Individual Developer Key
/<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 keys 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. |
Roles | Character List | Yes | Required if TemplateId is null. | The roles 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 Roles does not contain a data role. | 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. |
Editable | Boolean | No | No | If true, the current user can modify the key record. |
Deleted | Boolean | No | No | If true, the record has been deleted by a user, and is no longer an active key. These records are omitted from the All Developer Keys service, but are directly accessible by ID or from the deleted keys service. |
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. |
CreatedTimestamp | Timestamp | No | No | The time the key was created. |
ModificationTimestamp | Timestamp | No | No | The time the key was last updated. |
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 |
---|---|---|---|---|
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. |