MyBuilding API uses the OAuth 2.0 protocol for simple, but effective authentication and authorization. The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://). MyBuilding only support the password grant_type (http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.3), which allow the client to send the username / password and receive an access_token (2-legged oauth authentication)

Do you need to authenticate?

Some requests require authentication - specifically requests made on behalf of a user. 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 email 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 - Value must be password for this flow.
  • 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.mybuilding.org/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.mybuilding.org\/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.

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.mybuilding.org/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

 

PHP OAuth 2 Client:

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

Example usage:

 '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 '
';
    print_R($e);
    echo '
'; }