ActiveBuilding API uses the OAuth 2.0 protocol for authentication and authorization. All requests to the API must be made over SSL (https://, not http://). ActiveBuilding only supports the password grant_type: clients send a username and password and receive an access_token (2-legged oauth authentication).

Do you need to authenticate?

Requests made on behalf of a user require authentication. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future.

Receiving an access_token

The consumer can use the end-user’s username and password to request an access token.

The consumer should make an out-of-band POST request to the token endpoint, with the following parameters:

• grant_type – Must be password.
• client_id – Consumer key from the remote access application definition.
• client_secret – Consumer secret from the remote access application definition.
• username – End-user username.
• password – End-user password.

The following is an example of the body of the out-of-band POST:

curl -v -X POST https://api.activebuilding.com/oauth/access_token -d "grant_type=password&client_id=f3834ee69fab4d26a01f0c1fceb0f08a&client_secret=d938522c5058468fb8d9e6c0a987319e&username=testuser%40buildingname.com&password=mypassword"

If successful, this call will return a neatly packaged OAuth Token that you can use to make authenticated calls to the API. We also include the user who just authenticated for your convenience:

    "access_token": "d023e13c563b8825e458a82fea70154006aae8d7",
    "user": {
        "userId": "1142",
        "userType": "STAFF",
        "email": "testuser@building.com",
        "fullname": "John John",
        "profilePicture": "https:\/\/s3.amazonaws.com\/assets.activebuilding.com\/Profile\/1142.jpg"
    }
}

Note that we do not include an expiry time. Our access_tokens have no explicit expiry, though your app should handle the case that either the user revokes access or we expire the token after some period of time. In this case, your response’s meta will contain an “{"response":{"message":"invalid_grant"},"status":"failed"}”. In other words: do do not assume your access_token is valid forever.

If a problem occurs during this step, the response contains an error message with these parts:

• error – Error code
• error_description – Description of the error with additional information.
  
  
  
  • unsupported_response_type – response type not supported
  • invalid_client_id – client identifier invalid
  • invalid_request – HTTPS required
  • invalid_request – must use HTTP POST
  • invalid_client_credentials – client secret invalid
  • invalid_grant – invalid user credentials

Any login error not listed receives a generic authentication failure with text describing the error.

{
  "error":"authentication_failure",
  "error_description":"invalid password"
}

Get the user communities

A singe user can be associated to multiple communities. After you receive the access_token, you should get the user’s community list:

curl -v -X GET "https://api.activebuilding.com/communities?access_token=[ACCESS_TOKEN]"


   "response":{
      "communities":{
         "community":[
            [
               {
                  "communityId":"10",
                  "title":"140 Riverside"
               }
            ]
         ]
      }
   },
   "status":"success"
}

Staff / Resident Users

• Resident users (userType RESIDENT) usually only allow to see public or private information related only to their account.
• Staff users (userType STAFF) are allowed to perform additional actions that avilable only for staff users, such as adding packages, or getting the package list of the entire community

Requests

Once you have an access token. It’s easy to use any of the endpoints, by just adding access_token=ACCESS_TOKEN to your GET or POST request.
For example, from the command line, you can do

curl https://api.activebuilding.com/packages?communityId=[COMMUNITY_ID]&access_token=[ACCESS_TOKEN]]

PHP OAuth 2 Client:

https://github.com/adoy/PHP-OAuth2

Example usage:

<?php 
require_once 'Client.php';
require_once 'GrantType/IGrantType.php';
require_once 'GrantType/Password.php';

const CLIENT_ID     = 'f3834ee69fab4d26a01f0c1fceb0f08a';
const CLIENT_SECRET = 'd938522c5058468fb8d9e6c0a987319e';

const TOKEN_ENDPOINT         = 'https://api.activebuilding.com/oauth/access_token';

$parameters = array(
    'username' => 'testuser@building.com',
    'password' => 'mypassword'    
);

try {
    $client = new OAuth2\Client(CLIENT_ID, CLIENT_SECRET);
    $response = $client->getAccessToken(TOKEN_ENDPOINT, OAuth2\GrantType\Password::GRANT_TYPE, $parameters);
    
    echo 'access_token is ' . $response['access_token'];
        
} catch (Exception $e) {
    echo '
<pre>';
    print_R($e);
    echo '

’;
}