Authorization

OAuth 2.0 is a framework that allows third-party applications to request access to protected resources (e.g., Buildings, Tenants, Door Release Events) in the ButterflyMX API. This guide explains ButterflyMX’s OAuth implementation and how your application can integrate with it.

Redirect the User to the Authentication Page

To start the authorization process, your application needs to construct a URL similar to the following and redirect the user to it:

https://accountssandbox.butterflymx.com/oauth/authorize?client_id=HERE&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_secret=HERE

The redirect_uri defaults to urn:ietf:wg:oauth:2.0:oob for development purposes but can be customized upon request.

Once the user is redirected to the above URL, they will be prompted to log in via a web form. After successful authentication, the form will return an authorization code, which you can exchange for access and refresh tokens.

Exchange the Authorization Code for an Access Token

To obtain an access token, submit a POST request using the following format:

curl --location --request POST 'https://accountssandbox.butterflymx.com/oauth/token' \
--form 'grant_type=authorization_code' \
--form 'code=HERE' \
--form 'client_id=HERE' \
--form 'client_secret=HERE' \
--form 'redirect_uri=urn:ietf:wg:oauth:2.0:oob'

Sample Response:

{
    "access_token": "....",
    "token_type": "Bearer",
    "expires_in": 86400,
    "refresh_token": "....",
    "scope": "public",
    "created_at": 1726419574
}

The access token is valid for 24 hours. The refresh token does not expire and can be used to obtain a new access token.

Refresh the Access Token

To refresh the access token, submit a POST request as shown below:

curl --location --request POST 'https://accountssandbox.butterflymx.com/oauth/token' \
--form 'grant_type=refresh_token' \
--form 'client_id=HERE' \
--form 'refresh_token=HERE'