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
Available Services
Developer Key Description
Expansions

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.