Before requesting any tokens, you need to be a registered developer program participant. After this, using the same page, you can start registering applications and use them for obtaining access tokens from AirGMS users.

To obtain access token, you need to perform two steps:

  • Get authorization from iGMS user
  • Get access token based on authorization code

Getting a user authorization

The first step is to get authorization from the user. Point iGMS user to this page (line breaks added for better readability):

https://igms.com//app/auth.html?
    client_id=CLIENT_ID
    &redirect_uri=REDIRECT_URI
    &scope=SCOPE
    &state=STATE
  • client_id=CLIENT_ID - The client ID you received when you first created the application (labeled as "client_id" in the list of your applications)
  • redirect_uri=REDIRECT_URI - Indicates the URI to return the user to after authorization is complete (labeled as "redirect_uri" in the list of applications)
  • scope=SCOPE - One or more scope values indicating which parts of the user's account you wish to access. When you need to use more than one scope, present them as a comma-separated string, i.e. scope=tasks,listings. As for now, these scopes are available:
    • tasks: gives you access to company info, list of team members and tasks assigned to them
    • messaging: gives you access to view listings, bookings, guests, hosts, and to send messages to booking guests
    • listings: gives you access to view listings, hosts, and to change status of listings (to listed/unlisted)
    • calendar-control: gives you access to change calendars’ data (prices, currency, availability, minimum stay)
    • direct-bookings: gives you access to view calendars’ data, and to create/edit direct bookings
    • pricing-management: gives you access to view calendars’ data, and to suggest prices, minimum stay, and availability
    • smart-locks: gives you access to view bookings and properties, and to assign smart locks access codes to them
    • external-cleaning-management: gives you access to view booking, properties and calendar data;
    • reports: gives you access to CSV report downloading;
  • state=STATE - A random string generated by your application, which you'll verify later, when user will be redirected back to your REDIRECT_URI. This param is optional.

The user sees the authorization prompt on the iGMS site where he can either allow or deny your request. If they deny authorization request, they will be redirected to the modified REDIRECT_URI having the access_denied value for the error parameter. If the user clicks "Allow," they will be redirected back to your site with an auth code:

https://example.org/path?code=AUTH_CODE&state=STATE
  • code=AUTH_CODE - Authorization code which you will use in the next step.

  • state=STATE - The server returns the same state value that you passed. If you have not set state in authorization request, redirect URI will not contain this parameter, too.

    You should first compare this state value to ensure it matches the one you started with. You can typically store the state value in a cookie or session, and compare it when the user comes back. This ensures your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.

Getting an access token

Next step, your server exchanges the auth code for an access token. This step can be performed without any iGMS user participation, since they grant you authorization code required for this step. Create request to this endpoint (line breaks added for better readability):

https://igms.com/auth/token?
    grant_type=authorization_code
    &code=AUTH_CODE
    &redirect_uri=REDIRECT_URI
    &client_id=CLIENT_ID
    &client_secret=CLIENT_SECRET
  • grant_type=authorization_code - The grant type for this flow is authorization_code, the only correct value.
  • code=AUTH_CODE - This is the code you received in the previous step when user was redirected to your site.
  • redirect_uri=REDIRECT_URI - Must be identical to the redirect URI provided in the previous step.
  • client_id=CLIENT_ID - The client ID you received when you first created the application (labeled as "client_id" in the list of your applications).
  • client_secret=CLIENT_SECRET - Since this request is made from server-side code, the secret can be safely included. If client_secret has been set in application editor, this field should be included in the request and contain the same string. If client_secret has not been set for the app, the field should not be included in this request.

iGMS server replies with an access token:

{
    "access_token": "some-access-token"
}

Or, if there was an error:

{
    "error": "Incorrect application credentials"
}

Now you can use received access token for making API requests. Access token allows you to make up to 1000 requests per minute.