Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Open Houses Overlays Overlays: Shapes Portals Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

OpenID Connect

Important!

Never provide your access_token, refresh_token or client_secret to a web browser or other end-user agent. Instead, maintain a separate session and persist this data in a location accessible only by your application (e.g. do not store the access_token in a cookie). Contact api-support@sparkplatform.com for further guidance.

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. The standard is controlled by the OpenID Foundation.

  1. Authorization Code Walkthrough
  2. Deleting Access Tokens
  3. Single Logout
  4. Revocation
 

Authorization Code Walkthrough

The Spark® Identity Provider (IdP) adds an extension to support OAuth 2.0 requests inside a single OpenID request.

All OpenID Connect requests must be made using HTTPS.

 
 

The typical OpenID Connect/OAuth2 flow with Spark API can be broken down into four steps:

  1. Obtaining User Authorization
  2. Token Exchange
  3. Requesting Data
  4. Refreshing Expired Sessions
 

Obtaining User Authorization

Endpoints:

You can obtain our OpenId Configuration information at https://sparkplatform.com/.well-known/openid-configuration. As specified in the OpenID Connect Discovery Specification. Most programming languages will have libraries pre-built to easily integrate OpenID Connect.

See also section 3.1 of OpenID Connect Core.

Obtaining user authorization requires you to redirect the end-user to the appropriate endpoint with the required parameters provided. Once they have authorized your application, they will be redirected back to your redirect_uri with the access code provided in the URI.

Example Request
https://sparkplatform.com/openid/authorize?client_id=1234&scope=openid&response_type=code&redirect_uri=https://example.com/callback&state=abcdefgh&nonce=zyxwvuts

If the request is valid, the OpenId response will contain code. After receiving the OAuth 2 code, your consumer script can proceed with the OAuth 2 token exchange and OAuth 2 data request.

Example: Successful Response
https://example.com/callback?state=abcdefgh&code=c07pue969wqlz6u5clvm2gypz
 

Note that OpenID responds with many more parameters, but these two are the most important for an OAuth 2 example. You will use the code within the callback to request a token shown in the Token Exchange example below.

 

Token Exchange

See also OpenID Connect Core Token Endpoint.

After the end user has successfully authorized your application, you must exchange your access code for an access_token by POSTing the the following data to the https://sparkplatform.com/openid/token resource:

 
Sample POST Request Body
{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "authorization_code",
  "code": "[code]",
  "redirect_uri": "[redirect_uri]",
}
 
Attribute Description
client_id This is your OAuth client ID provided by FBS.
client_secret This is your OAuth client secret provided by FBS.
grant_type This is always set to authorization_code .
code This is the value of the code obtained in step 1.
redirect_uri The value of the URI to which the user will be redirected upon completion. The domain must match that which is registered with FBS. (We encourage you to use HTTPS for your redirect URI.)
 
Sample Successful Response Body: HTTP status 200
{
  "access_token": [access_token],
  "expires_in": 86400,
  "refresh_token": [refresh_token],
  "token_type": "Bearer",
  "id_token": [id_hash]
}
 
Sample Failed Response Body: HTTP status > 299
(see also OpenID Connect Core Token Error Response)
 
{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}
 

Requesting Data

Authorization: Bearer [access_token]
 

Note that, when using OAuth 2, all requests must be made over HTTPS.

 

Refreshing Expired Sessions

Access tokens expire after 24 hours, yet it would be undesirable to have to redirect end users to the OAuth 2 authorization flow once a day. The refresh flow is a remedy to this.

 
Sample Session Expired Response Header and Body
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm='Flexmls API', error='invalid_token'
{
  "D": {
    "Success": false,
    "Message": "Session token has expired",
    "Code": 1020
  }
}

To refresh the access token, POST the following JSON data to the API's OAuth Access Token service at https://sparkplatform.com/openid/token using HTTPS:

 
Sample POST Request Body
{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "refresh_token",
  "refresh_token": "[refresh_token]"
}
 
Parameter Description
client_id This is your OAuth client ID provided by FBS.
client_secret This is your OAuth client secret provided by FBS.
grant_type Set this to refresh_token .
refresh_token This is the value of the refresh token obtained from the initial access token grant.
 
Sample Successful Response Body: HTTP status 200
{
  "access_token": "example_new_access_token",
  "refresh_token": "example_new_refresh_token",
  "expires_in":  86400,
  "token_type": "Bearer",
  "id_token": [id_hash]
}
 
Sample Failed Response Body: HTTP status > 299
(see also OpenID Connect Core Token Error Response)
 
{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}
 

Deleting Access Tokens

/<API Version>/oauth2/token/<Token>

HTTP Method Description Notes
DELETE Destroy an existing token, expiring it immediately.  

Delete Request

Parameters:

 

DELETE Response

The standard success/fail response is returned.

 

Single Logout

Spark Platform provides a single log out service that can be accessed directly from the following URI:

https://sparkplatform.com/openid/logout
 

The Single Logout process destroys the existing cookie at our OpenID Connect endpoint, requiring the user log in the next time they are directed to the endpoint. It also destroys custom sessions for other applications built on the Spark Platform, so long as those applications have specified a Single Logout URI in the Spark Store.

 
Parameter Description
client_id This is your OAuth client ID provided by FBS. Only required if post_logout_redirect_uri is provided.
post_logout_redirect_uri If provided, the user will be redirected back to this URI after logging out. This must match the redirect_uri for the client_id.
state (Optional) Will be returned to your post_logout_redirect_uri. See this documentation for preferred usage.
 

Revocation

Spark Platform provides a revocation service that can be accessed directly from the following URI:

https://sparkplatform.com/openid/revoke
 

You can direct users to the revocation endpoint if you want to allow them to remove your application's authorization. Which will require the user's consent for API access the next time you make a request on their behalf. You can also send a POST request to the revoke endpoint to invalidate your keys. Look at Section 2.1 of OAuth 2.0 Token Revocation for more information.