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. Deleted Developer Keys
    3. 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

/<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,
            "IdentityId": 101,
            "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,
            "IdentityId": 101,
            "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.
IdentityId Integer No No The unique id for the identity the key belongs to.
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.
OpenIDEnabled Boolean Yes No If true, the key has access to the OpenID endpoint. Defaults to true.
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.
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.

API Explorer

The API Explorer does not currently support this service.