Introduction

Lofty's Open API and Developer Platform provide developers with various ways to serve their mutual customers. In this Help Center article, we will go over the different options you have to connect your application or service to Lofty. 

You can access Lofty's Open API by visiting https://api.lofty.com/docs/index.html 

Summary

• Which option is best for you?
• Basic API Connection
• Developer Platform

  • Create a Developer Account

  • Complete Third-Party Risk Assessment
  • Register an Application
  • Review Process/Results
  • OAuth 2.0 Implementation
  • Vendors Accessing User Data

 

Which option is best for you?

Basic API Connection

Developer Platform

You will use Lofty’s API documentation to connect your product or service Lofty will not be involved at all. Pros: No developer account or authorization from Lofty is required. No security assessment required Cons: You must manually obtain an API key from every individual user whom you connect. Limited rates - only 10 API calls per minute

You will create a developer account and submit applications for approval by Lofty. You will still use Lofty’s API docs to build the actual integration You are required to do a security assessment (built into the developer platform) Pros: OAuth, SSO supported Higher rate limit - 500 API calls per minute Cons: Applications may be denied Approval process may take longer than API Only The only involvement from Lofty is to review applications and security assessments

 

Basic API Connection

Lofty has an "Open API," meaning users or vendors can access available endpoints as long as they have account credentials.

Our Open API does not require a developer account to access, and can be connected to any individual user.

 

(1) API Key

If you are a Vendor who needs to access a User's API key, guide them to go to Settings > Integrations > API.

If you are a User integrating another application with Lofty and it asks for your Lofty API key, here is where you can find that. Navigate to Settings > Integrations > API:

 

Developer Platform

If you are seeking a more connected experience with Lofty, we recommend leveraging the Developer Platform. With a Developer account, you will be able to connect to other users on Lofty using OAuth 2.0.

OAuth 2.0 is an open standard for account access authorization without requiring passwords to be provided to third parties. This method provides developers with a secure way to access Lofty API data on behalf of Lofty platform users. Most commonly, OAuth 2.0 authentication is useful to set up integrations between third-party applications (referred to as "vendors") and Lofty.

For reference, here is Lofty's API https://api.lofty.com/docs/index.html

 

• Create a Developer Account
• Register an Application
• Review Process/Results
• OAuth 2.0 Implementation
• Lofty User Experience

 

Create a Developer Account

First, access the Lofty Developer Platform. 

 

To create a developer account, click on the Sign Up link:

 

Provide all of the required information and then click Sign Up:

 

Your credentials should be auto-generated so you can click on the login button to access your new developer account:

 

Complete Third-Party Risk Assessment

Before you can register your application, you must complete your profile and submit your Third-Party Risk Assessment. There are 2 methods to complete this step - either with a SOC2 Report or by completing the Third-Party Risk Assessment Questionnaire.

Your Third-Party Risk Assessment must be reviewed and approved by a member of Lofty's Developer team before you will be able to register your application.

• If you are working with an internal contact, please email them when you have completed this step. If you do not have an internal contact, please email support@lofty.com.
• Here's a template that you can copy and paste:
  • Hi there! I am an external vendor looking to integrate with Lofty on the Developer Platform and just submitted my Third Party Risk Assessment. Please create a ticket for the Developer team to complete the Third Party Qualification Review. The name of my Company is [THE NAME OF YOUR COMPANY].

 

Register an Application

*Note: You can repeat this process multiple times if you have multiple applications that you are connecting with Lofty.

 

Once your Third-Party Risk Assessment has been approved, you will will be able to submit your applications in the My Authorization tab.

 

To start a new application, click on the + Add More Authorizations button:

 

Provide all of the required information and then click on the Submit button to apply.

• App Name
• Website
• Authorized Redirect URL
  • The "Authorized" or "Denied" status will also be returned in this URL
• Description
• App Logo
• Primary Contact Name
• Primary Email
• Primary Phone Number
• Permissions

 

• If you are working with an internal contact, please email them when you have completed this step. If you do not have an internal contact, please email support@lofty.com.
• Here's a template that you can copy and paste:
  • Hi there! I am an external vendor looking to integrate with Lofty on the Developer Platform and just submitted my Application. Please create a ticket for the Developer team to complete the Vendor API Authorization. The name of my Company is [THE NAME OF YOUR COMPANY].

*IMPORTANT: If at any time you need to change or update your application details, please reach out to your internal contact or the Lofty Support Team (support@lofty.com), they must submit the change on their end.

 

Review Process/Results

After submitting your application, you will be able to monitor the status via the Lofty Developer Platform. Simply log in access your authorization dashboard and review the Status column at the far right.

 

Under Review

This status will display until the application is reviewed and either approved or rejected. 

• If you are working with an internal contact, please email them when you have completed this step. If you do not have an internal contact, please email support@lofty.com.
• Here's a template that you can copy and paste:
  • Hi there! I am an external vendor looking to integrate with Lofty on the Developer Platform and just submitted my Application. Please create a ticket for the Developer team to complete the Vendor API Authorization. The name of my Company is [THE NAME OF YOUR COMPANY].

 

Rejected

If rejected, the primary contact submitted with the application will receive an email with more details on why it was rejected. You can then click the Resubmit button to edit the information provided before submitting again.

 

Approved

If approved, you will see the client_id and client_secret in your account. You will need this information for the next step.

client_id

client_secret

As of now, our vendor platform only supports one callback URL per application,  which means that if there are multiple environments that need to be tested out, such as pre-release, sandbox, and production, the recommended action would be to applying for multiple applications, one for each environment.

Please see the sample below. Multiple applications have been successfully submitted by the team, and we have approved them. 

Once the demo account access is granted, your team can proceed with development and test it out by following the process below:

Step 1: https://lofty.com/page/vendor-auth.html?clientId={Replace with your client ID associated with your approved app}

 

Step 2: Authorize, and we will redirect to the callback link you provided:

curl {rediectURL}?code=XXXXXXXXXXXXX' 

 

Step 3: YOUR SERVER NEEDS TO USE the code to obtain the token – this is something your team has to implement to automatically call it:

 

Sample curl for your reference:

curl --location 'https://crm.lofty.com/api/user-web/oauth/token?code=XXXXX&client_id=XXXX&redirect_uri=XXXXXX&grant_type=authorization_code' \

--header 'Authorization: Basic XXXXXX' \

--header 'Content-Type: application/x-www-form-urlencoded'

 

Note 1: The value of the Authorization header is the Base64 encoded version of clientId:clientSecret

Note 2: Code in the request param is the one you obtained in step 2.

 

OAuth 2.0 Implementation

• User Authentication
• Using Auth_Code to get Access Token and Refresh Token
• Refreshing Access Token

In this section, we will discuss setting up OAuth 2.0 to authenticate users of your app and then demonstrate how to make a call to Lofty's API using the Access Token. This diagram is provided as a visual representation of this process:

 

User Authentication

Before your application can access private data using Lofty's API, it must obtain an Access Token that grants access. There are several ways to make this authorization request, for example, a JavaScript application might request an access token using a browser redirect to Lofty.
Once redirected to Lofty, the user needs to log into their Lofty account. After logging in, the user is asked whether they are willing to grant the permission that their application is requesting. This process is called user consent.

Your server doesn't need to do anything at this stage except wait for a response from the Lofty server to indicate whether the access is granted or not.

 

HTTP

https://lofty.com/page/vendor-auth.html?clientId=${clientId}

 

Parameter Description

 

The Lofty server will send the response to the Authorized Redirect URL you submit in your application. The Auth_Code or error message that is returned to your server appears on the query string, as shown below:

 

Auth_Code Response

If the user grants permission, the Lofty Server will send the Auth_Code to the Authorized Redirect URL.

 

HTTP

⁣https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7⁣ 

 

Error Response

If the user does not grant permission, the server returns an error.

 

HTTP

https://oauth2.example.com/auth?error=access_denied

 

Using Auth_Code to get Access Token and Refresh Token

After your application server receives the Auth_Code, you can use it to exchange the Access Token and Refresh Token.

You can then use the Access Token to call Lofty's API on behalf of the user.

 

HTTP

⁣POST api/user-web/oauth/token HTTP/1.1
Host: crm.lofty.com
Content-Type: application/x-www-form-urlencoded
Headers:
Authorization:Basic atughMaQm6bTrgtp7bas=

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

 

Parameter Description

 

The following is the description of the returned fields:

 

Refreshing Access Token

Access tokens periodically expire and become invalid. You can use the Refresh Token to refresh and obtain a new Access Token without prompting the user for permission

 

HTTP

⁣POST api/user-web/oauth/token HTTP/1.1
Host: crm.lofty.com
Content-Type: application/x-www-form-urlencoded
Headers:
Authorization:Basic atughMaQm6bTrgtp7bas= 

refresh_token={your refresh_token}&
grant_type=refresh_token

 

Parameter Description

 

The following is the description of the returned fields:

 

Lofty User Experience

As a sample of what the user experience would look like if this was configured, please reference Managing Authorization by Third-Party Apps & Services.

 

Vendors Accessing User Data

Make sure you have your Client ID handy. For this sample, we're going to use YOURCLIENTID

The authorized redirect URL provided by vendor to receive code is https://YOURAPP.com/redirect

Vendors cannot pull data from any Lofty users unless the Lofty user started the integration themselves.

 

If a Lofty user wants to use wants to use your approved app

1. Make sure they are logged in to Lofty on their browser
2. The Lofty user can find your app using your link: https://crm.lofty.com/page/vendor-auth.html?clientId=YOURCLIENTID
3. The Lofty user will click Authorize to add your app 

 

Our system will validate the Lofty user's account login cookies and your Vendor ID. If both are successfully validated, then our system will generate a short-term authorization code and send to the provided vendor callBack URL (NOT TO the Lofty user)

Once you receive the code, use the following API to obtain the bearer token using the customer's authorization code:

curl --location 'https://crm.lofty.com/api/user-web/oauth/token?code=THEIRAUTHORIZATIONCODE&client_id=YOURCLIENTID&redirect_uri=YOURAPP.COM/REDIRECT&grant_type=authorization_code' \

--header 'Authorization: Basic {Base 64 of the client_id:clientSecret} \

--header 'Content-Type: application/x-www-form-urlencoded'

• This is only done on the Vendor side if they want to obtain the bearer token

After the bearer token is obtained, Vendors can use the token to get data from the Lofty user's account using Lofty Open API. This data can be used for your integrations or apps. 

Since the bearer token is provided to the vendor directly, Agents are not allowed to rotate them. If an agent wants to disconnect from a connected integration, they can by clicking Disconnect. 

 

Rebranding from api.chime.me to api.lofty.com

For vendors/partners utilizing the old API, you need to make this change before September 30, 2024. Please refer to the sample below:

FROM:
curl --location 'https://api.chime.me/v1.0/me' \
--header 'Content-Type: application/json' \
--header 'Authorization: XXXXXXXXXXXXXXX' \
--data ''

TO:
curl --location 'https://api.lofty.com/v1.0/me' \
--header 'Content-Type: application/json' \
--header 'Authorization: XXXXXXXXXXXXXXX' \
--data ''

 

Questions?

If you have any questions regarding this topic or any others, please contact our Support Team via email at support@lofty.com, by phone at 1 (855) 981-7557, or by chat through your Lofty CRM. 

 

Related terms: Open API, Developer Platform, OAuth, API, SOC, Third party assessment