OAuth 2

If you are not sure which authentication method to use, please read the Overview page.

All requests, including requests after the OAuth 2 authorization has been granted, must be made using HTTPS.

The Spark® API currently supports draft 10 of the OAuth 2 specification. Note that some developers will have a "single session" OAuth 2 key with an access_token and refresh_token already provided to them. Developers with these keys can skip steps one and two, starting instead at Requesting Data.

The Spark API also supports the Resource Owner Password Credentials flow for certain developers granted special permissions for retrieving an access_token on behalf of the end user. Developers using this flow will start here.

The typical OAuth 2 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
5. Deleting Sessions

i

Obtaining User Authorization

See also section 3 of the OAuth 2 spec.

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.

API Endpoints:

https://sparkplatform.com/auth/vow

https://sparkplatform.com/auth/vow/<Portal.Name>

Parameters:

• client_id : your unique client key, provided to you by FBS.
• mls: (optional, VOW only) If present, consumers will only be able to select agents from the mls with the Id provided.
• redirect_uri: the URI that you'd like the OAuth endpoint to redirect to after successfully authenticating the user. The URI you provide to us must match the URI we have on record for your key.
• redirect_when_no_connected_agents: (optional, VOW only) If present, consumers will be redirected back to the redirect_uri if they have no agents to work with.
• response_type : this should always be set to code .
• state : an optional parameter that will be returned to your redirect_uri.
• unconnected : (VOW only, MLS-level portals only) If present, consumers that sign up for an account at that endpoint will be created as unconnected consumers. This value will be true when the portal is specified in the OAuth2 endpoint:
   

  https://sparkplatform.com/auth/vow/myportal?unconnected=true

   
  When using the standard vow endpoint, the value will be the portal name of the user you'll want the unconnected contact to be created under:
   

  https://sparkplatform.com/auth/vow?unconnected=myportal

https://sparkplatform.com/oauth2?response_type=code&client_id=[client_id]&redirect_uri=[redirect_uri]

https://my.site.com/callback?code=[access_code]

https://my.site.com/callback?error=redirect_uri_mismatch&error_description=Parameter+redirect_uri+does+not+match+registered+URI

Token Exchange

See also section 4.1.1 of the OAuth 2 spec.

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://sparkapi.com/v1/oauth2/grant resource:

Sample POST Request Body

{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "authorization_code",
  "code": "[code]",
  "redirect_uri": "[redirect_uri]"
}

Sample Successful Response Body: HTTP status 200

(see also section 3.1 of the OAuth 2 spec)/p>

{
  "access_token": "[access_token]",
  "refresh_token": "[refresh_token]",
  "expires_in":  86400
}

Sample Failed Response Body: HTTP status > 299

(see also section 3.2.1 of the OAuth 2 spec)

{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}

Resource Owner Authorization

See also section 4.1.2 of the OAuth 2 spec.

In this instance, you retrieve your access token by prompting the end user for their username and password and sending those directly to the https://sparkapi.com/v1/oauth2/grant resource and receive the json response directly from the request.

Sample POST Request Body

{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "password",
  "username": "[username]",
  "password": "[password]"
}

Sample Successful Response Body: HTTP status 200

(see also section 3.1 of the OAuth 2 spec)

{
  "access_token": "[access_token]",
  "refresh_token": "[refresh_token]",
  "expires_in":  86400
}

Sample Failed Response Body: HTTP status > 299

(see also section 3.2.1 of the OAuth 2 spec)

{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}

Requesting Data

See also section 5.1.1 of the OAuth 2 spec.

Once you have your access_token, you can request data by placing it in the Authorization header for each request:

Authorization: OAuth [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: OAuth realm='Flexmls API', error='expired_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://sparkapi.com/v1/oauth2/grant using HTTPS:

Sample POST Request Body

{
  "client_id": "[client_id]",
  "client_secret":  "[client_secret]",
  "grant_type": "refresh_token",
  "refresh_token": "[refresh_token]"
}

Sample Successful Response Body: HTTP status 200

(see also section 3.1 of the OAuth 2 spec)

{
  "access_token": "example_new_access_token",
  "refresh_token": "example_new_refresh_token",
  "expires_in":  86400
}

Sample Failed Response Body: HTTP status > 299

(see also section 3.2.1 of the OAuth 2 spec)

{
  "error": "[error_code]",
  "error_description": "Detailed message here"
}

Deleting Sessions

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

Delete Request

Parameters:

• None

DELETE Response

The standard success/fail response is returned.