App Store

OAuth Single Sign-On

The App Store uses OAuth 2.0, an open authentication protocol. Using OAuth 2.0, applications can safely share access to data. Entrata provides OAuth 2.0 tokens and acts as the authority for the single sign-on. Individual applications can request and submit data on behalf of a user, with their permission. This permission is implicitly granted when a user installs the app and tokens are granted when a user clicks into the app. The official specification for OAuth 2.0 can be found here.

After a user installs your app and clicks into it, an iFrame will be loaded with the default URL that you provide. We will append two parameters to the end of the URL. The first parameter (referrer) is used to identify that the request comes from Entrata. The second parameter (auth_code) is the used in the first step of OAuth 2.0, requesting an access token. An example app URL might look like this:

http://[app_url]/login?referrer=propertysolutions&auth_code=aKXbU6aPdDB6TlqLYygl5CWy4A==

Your application should recognize the request as coming from Entrata. Using the auth code, your application makes a server-to-server request for an access token from Entrata. This must take place quickly, as the lifetime of the auth code is very short. Once you have an access token, it may be used to access information about the user logging in. You can use Entrata's API to request the access token at https://sync.entrata.com/api/oauth. For example, a request using JSON would look like this:

{
  "auth": {
    "type": "oauth",
    "code": [auth_code],
    "grant_type": "authorization_code",
    "client_id": [client_id],
    "client_secret": [client_secret]
  },
  "method": {
    "name": "getAccessToken",
    "params": {
    }
  }
}

Once you have been issued an access token, you can use it to make web service calls. The first call you should make is getUserInfo. This will return user information from the Entrata system. The id is unique to the user logging in. Additionally, the response will include the management company name, property information for properties accessible by the user, and the unique subdomain for the maangement company. This subdomain will be used for making additional web service calls. For more information on how to make that call, see the section below.

After you receive the user ID, two scenarios are possible. If you recognize the user ID from a previous authentication, you can authenticate your user on your application. To the user, access to the site will appear seamless. If you do not recognize the user id, you will display a login page, while temporarily storing the user ID and access token. Once the user has authenticate, you can associate the ID and the access token provided by Entrata to the newly authenticated user. Depending on your application, you may want to allow for many to one mapping of Entrata credentials to your user. (i.e. multiple ids and associated access tokens would map to a single user in your application). The next time they log in, you will be able to recognize the user ID and log them in directly. The access token will be different every time you request one for any given user.

For a visual representation of this process, please see the graphic to the right, or download the pdf.

Accessing Web Services

Once a user has been authenticated, your application can access Entrata's web services using the access token you received. These web services allow your application to submit data to and receive data from Entrata. The documentation for the available web services can be found here. Access to user data will be contingent upon the set of data scopes defined when your app is submitted to the App Store. When the user installs your app, they provide permission for the data access outlined. You will only be able to make web service calls that belong to one of those pre-defined scopes.

Entrata' web services are a set of RPC-based APIs. They will accept post data as JSON or XML, though XML may be preferred for more complex web service calls such as some of the MITS services. For more basic calls, JSON is preferred. The response will match the request format and should be specified in the "Content-Type" HTTP header. The URL endpoint depends upon the call being made. For example, if you are making the getCustomers service, you would post to https://[subdomain].entrata.com/api/customers.

The App Store API authentication method differs from general API usage:

• The authentication type is oauth and does not use a username/password.
  You have an access token that will be used for authentication. You should send the accces token in the Authorization header, per the OAuth 2.0 specification. (Authorization : Bearer [access_token]) There is no need to pass any other authentication parameters.

Below is a sample request using an OAuth 2.0 access token. It would be specified in the header, which is not shown below.

{
  "auth": {
    "type": "oauth"
  },
  "method": {
    "name": "getCustomers",
    "params": {
      "property_id": [property_id],
    }
  }
}

For more detailed information on accessing the Entrata API, please refer to the documentation provided.