Authentication

This documentation has moved to the Spark Platform website. Please click here to view.

The flexmls API authentication services establish an access or session token to be used for subsequent calls to flexmls API services. There are two major ways of authenticating and thus establishing a session with the flexmls API, depending on how the developer’s API key is configured and the needs of the application:

  • OAuth 2. This is the approach necessary to write applications that need portal (agent’s client) access. OAuth enables the developer to write software that works on behalf of an agent’s client. The user is required to provide their credentials (username and password) in exchange for an OAuth access token.
  • flexmls API authentication. This is used when writing IDX products that act on behalf of a single flexmls user. Someone at FBS needs to configure the API key to point at a single flexmls user, and since this is an IDX product, will need to buy a subscription to the IDX API (more details here). An example of a working product using this is the flexmls IDX WordPress Plugin. Since developers are provided a development API key and a working product requires the use of a real API key, your application will need a way for the flexmls user’s API key and secret to be entered and used in requests to the flexmls API.

If there are questions on the API key’s configuration, please ask the FBS employee who provided the key. More information about API key roles may be found here.

 

OAuth 2

The flexmls API currently supports draft 10 of the OAuth 2 specification.

OAuth allows authenticating on behalf of portal (or “consumer”) users. The process to obtain an access token is as follows. If you already have obtained an access token and it has not expired, you may skip directly to step 4.

  1. Redirect the user’s browser to the appropriate OAuth endpoint, along with parameters discussed below. Note that HTTPS is required on the endpoint. See also section 3 of the OAuth 2 spec.

    API Endpoints:

    • Portal (consumer) authentication:
      API key permission(s) How to obtain the OAuth endpoint URI
      IDX role with both IDX and Portal permissions Make a request with IDX permissions (and flexmls API authentication) to the System Info service, then use the URI from the OAuth2ServiceEndpointPortal attribute for the portal OAuth endpoint. This will allow the application to dynamically retrieve the agent’s portal name.
      IDX role with only Portal permissions Obtaining authorization on behalf of a consumer for API keys that only have portal permission requires that the OAuth endpoint is hard coded to https://portal.flexmls.com/r/login/portalname in the application, though you may wish to allow the end user to enter the portalname parameter. The portalname parameter must be replaced with the agent’s portal name, e.g. SampleAgent.

    Parameters:

    • client_id : this is similar to the flexmls API key, but is a separate key for OAuth. FBS will provide this to you.
    • redirect_uri : this should contain the URI that you’d like the OAuth endpoint to redirect to after successfully authenticating the user
    • response_type : this should always be set to code .
  2. Upon successful authentication, the OAuth endpoint will redirect back to the URI specified in the redirect_uri parameter, with a code parameter passed to it.
  3. POST the following JSON data to the API’s OAuth Access Token service at http://api.flexmls.com/v1/oauth2/grant using HTTPS, after which an OAuth access token will be returned (see also section 4.1.1 of the OAuth 2 spec). Note that this step does not occur in the end user’s browser; it’s an API request.

    Sample POST Request Body

    {
      "client_id": "[client_id]",
      "client_secret":  "[client_secret]",
      "grant_type": "authorization_code",
      "code": "[code]",
      "redirect_uri": "[redirect_uri]"
    }
    Parameter Description
    client_id This is your OAuth client ID provided by FBS, which is different than the API key.
    client_secret This is your OAuth client secret provided by FBS, which is different than the API key's secret.
    grant_type This is always set to authorization_code .
    code This is the value of the code obtained in step 2.
    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.

    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"
    }
  4. Using HTTPS, pass the OAuth access token obtained in the previous step in every subsequent API request as the following header, replacing [access_token] with the actual access token itself (see also section 5.1.1 of the OAuth 2 spec):

    Authorization: OAuth [access_token]

Access tokens expire after 24 hours. Refresh tokens are supported as follows.

Refresh tokens

To refresh the access token, POST the following JSON data to the API's OAuth Access Token service at http://api.flexmls.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]",
  "redirect_uri": "[redirect_uri]"
}
Parameter Description
client_id This is your OAuth client ID provided by FBS, which is different than the API key.
client_secret This is your OAuth client secret provided by FBS, which is different than the API key's secret.
grant_type Set this to refresh_token .
refresh_token This is the value of the refresh token obtained from the initial access token grant.
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.

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"
}

flexmls API Authentication

The flexmls API authentication procedure is as follows:

  1. The developer API key is signed and sent to the authentication service over SSL.
  2. The authentication service responds with a session token.
  3. Each subsequent request to the API must include a token and be properly signed.

Session tokens are good for a maximum of 24 hours, and have an idle timeout of 1 hour. After the session token has expired, authentication must occur again. Only one session token may be active for any single API key at one time.

Authentication is designed to require the use of a proxy service to avoid exposing the shared secret in a user’s browser.

Notes

  • Requests to the /session service must be made using HTTPS, but requests to other services may be made with HTTP or HTTPS.
  • Only one session token may be active for an API key at any time.

Session management (flexmls API auth only)

URI: /<API Version>/session

Verb Outcome Notes
GET Returns HTTP 405 (Method Not Allowed)

Extends the session for another timeout period
Not implemented

The GET response is the same as the POST response
POST Create a new session See parameters below
PUT Returns HTTP 405 (Method Not Allowed) Not implemented
DELETE Returns HTTP 405 (Method Not Allowed)

Terminates the current session immediately
Not implemented

Parameters for all requests

Parameter Required Notes
ApiKey Yes Your API key
ApiSig Yes Signature for this request, generated as described below

POST Request

To create a new session, POST to the following URI with an empty POST body, substituting the proper ApiKey and ApiSig parameters:

https://api.flexmls.com/v1/session?ApiKey=12345&ApiSig=2fde9e59147081ad4e39382e1f809710

Signature Generation

ApiSig, the signature for this request, is generated by creating an MD5 hexadecimal representation of the following string:

[secret]ApiKey[key]
  • [secret] is the secret pass-phrase assigned to your key (without the brackets)
  • [key] is your API key, without the brackets

Example: Assume [secret] is 1234 and [key] is abcd . The string to be processed with MD5 would then be:

1234ApiKeyabcd

The above string, when processed with MD5 will be:

2fde9e59147081ad4e39382e1f809710

Feel free to use the MD5 test page to verify that the signatures are correct.

POST Response

If a new session is successfully created, the response payload will look like the following:

{
  "D" : {
    Success: true,
    Results: [ {
      AuthToken: "xxxxx",
      Expires: "2010-10-30T15:49:01-05:00"
    }]
  }
}

Authenticated Requests (flexmls API auth only)

Subsequent calls to the API after a session is created may be made with either HTTP or HTTPS and have a similar format:

https://api.flexmls.com/v1/contacts?AuthToken=1234&ApiSig=3ebbd149f28c69c19fa0f38d5bb4d14

In all authenticated calls to the system, AuthToken and ApiSig are required.

Signatures for authenticated calls are generated by creating an MD5 hexadecimal representation of the following string:

[secret]ApiKey[key]ServicePath[service_path]param1[param1]...paramN[paramN][POST data]
  • [secret] is the secret pass-phrase assigned to your key
  • [key] is your API key
  • [service_path] is the path to the service being requested. For example, if the request is to https://api.flexmls.com/v1/contacts, the service path will be /v1/contacts.
  • [token] is your session token, returned from a successful authentication request
  • [param1]...[paramN] are all parameters sent with the request, in alphabetical order first by parameter name and then by parameter value. AuthToken will always be included in this parameter list for authenticated requests.
  • [POST data] If a POST request is made, the JSON data must be appended to the end of the string to sign.

Example: assume [secret] is 1234, [key] is abcd and full request is http://api.flexmls.com/v1/contacts?AuthToken=9876&name=John+Contact&email=contact@fbsdata.com&phone=555-5555&group=IDX Lead. The string to be processed with MD5 would be as follows:

1234ApiKeyabcdServicePath/v1/contactsAuthToken9876emailcontact@fbsdata.comgroupIDX LeadnameJohn Contactphone555-5555

Expiration of tokens (flexmls API auth only)

Tokens have a maximum life of 1 day (24 hours). The token will also expire if more than 60 minutes pass since the last request.

When a session expires, an HTTP 401 status code will be returned on any request to the API with the following payload:

{
  "D": {
    "Success": false,
    "Message": "Session token has expired",
    "Code": 1020
  }
}

When the token expires, an authentication call must be made to retrieve a new token. The original request must then be subsequently repeated.

Comments on this entry are closed.