API Intro

The Monscierge API will allow you to leverage our product features into your own applications by building on top of our APIs. The Monscierge API implements the OAuth2 standard for allowing applications to request permission on behalf of users. You can learn more about OAuth2 by reading the simplified guide. There are many existing OAuth2 libraries that applications can use for PHP, Ruby, Python, NodeJS.

Getting Started

In order to start using the Monscierge API, you will need to have an account with a Connect user. If you do not yet have one, you can create one for free. You will also need to register an application.

Authenticating

To authenticate into API resources, you will need an OAuth bearer token.

Client Credentials Exchange

You can exchange your application's client credentials (the ones used to log into the ConnectCMS and mobile app) for an OAuth token.

Send a POST request to https://content.monscierge.com/auth/oauth/token with the following post body:

Parameter Description
client_id The client ID for your application.
client_secret The client secret key for your application.
grant_type Should be set to client_credentials to exchange client credentials for a token.

You will get back a JSON object that looks like the one below:

{
    "access_token": "BcQvvGYp9nieHlGrmv3mLG0r",
    "expires_in": 1199,
    "refresh_token": "I3su1sxPKttkdSSrZYP_hBNPxLC5-14E",
    "token_type": "bearer"
}


Authorization Code Exchange Flow

You can send your users to an authorization page to allow them to grant your application permission to use their account. You will need to set up the redirect/callback URI for your application if you have not already.

Redirect a user to https://content.monscierge.com/auth/oauth/authorize with the following query string parameters:

Parameter Description
client_id The client ID for your application.
redirect_uri Your application's redirect/callback URI where the users are redirected to after authorizing the application.
response_type Should be set to code to receive an authorization code which will be used to exchange for a token.
scope List of grant scopes your application would like to request from the user.
Connect is the only valid scope at this time.

If the user allowed the authorization then you will get an auth code returned back to the redirect URI in the query string like below:

https://example.org?code=BcQvvGYp9nieHlGrmv3mLG0r

Send a POST request to https://content.monscierge.com/auth/oauth/token with the following post body:

Parameter Description
client_id The client ID for your application.
client_secret The client secret key for your application.
grant_type Should be set to authorization_code to exchange authorization code for a token.
redirect_uri Your application's redirect/callback URI where the user was redirected to after authorizing the application.
code The authorization code provided from the authorization redirect/callback URI.

You will get back a JSON object that looks like the one below:

{
    "access_token": "BcQvvGYp9nieHlGrmv3mLG0r",
    "expires_in": 1199,
    "refresh_token": "I3su1sxPKttkdSSrZYP_hBNPxLC5-14E",
    "token_type": "bearer"
}


Implicit Authorization Exchange Flow

The implicit authorization flow differs than the standard by not requiring a server to exchange the auth code for the OAuth token. The key difference is that the implicit does not include a refresh token the flow must be restarted once the token expires.

Redirect a user to https://content.monscierge.com/auth/oauth/authorize with the following query string parameters:

Parameter Description
client_id The client ID for your application.
redirect_uri Your application's redirect/callback URI where the users are redirected to after authorizing the application.
response_type Should be set to token to receive an authorization code which will be used to exchange for a token.
scope List of grant scopes your application would like to request from the user.
Connect is the only valid scope at this time.

If the user allowed the authorization then you will get an OAuth token returned back to the redirect URI in the hash path like below:

https://example.org#access_token=BcQvvGYp9nieHlGrmv3mLG0r&token_type=bearer&expires_in=1199


Connect User Password Exchange

You can exchange your Connect user credentials (the ones used to log into the ConnectCMS and mobile app) for an OAuth token.

Send a POST request to https://content.monscierge.com/auth/oauth/token with the following post body:

Parameter Description
client_id The client ID for your application.
client_secret The client secret key for your application.
grant_type Should be set to password to exchange user credentials for a token.
scope List of grant scopes your application would like to request from the user.
Connect is the only valid scope at this time.
username The username for a Connect user.
password The password for a Connect user.

You will get back a JSON object that looks like the one below:

{
    "access_token": "BcQvvGYp9nieHlGrmv3mLG0r",
    "expires_in": 1199,
    "refresh_token": "I3su1sxPKttkdSSrZYP_hBNPxLC5-14E",
    "token_type": "bearer"
}


Refresh Token Exchange

After an access token has expired you will need to refresh it to prevent requiring the user to authenticate the application again.

Send a POST request to https://content.monscierge.com/auth/oauth/token with the following post body:

Parameter Description
client_id The client ID for your application.
client_secret The client secret key for your application.
grant_type Should be set to refresh_token to exchange refresh token for a new token.
refresh_token The refresh token provided from an original OAuth token.

You will get back a JSON object that looks like the one below:

{
    "access_token": "BcQvvGYp9nieHlGrmv3mLG0r",
    "expires_in": 1199,
    "refresh_token": "I3su1sxPKttkdSSrZYP_hBNPxLC5-14E",
    "token_type": "bearer"
}

Try out the APIs

When making API requests, you will need to authenticate the request by setting the Authorization header to Bearer YOUR_ACCESS_TOKEN.

You should now be able to authenticate and access different API resources with an OAuth token.

Now that you're set up, go ahead and browse the API docs and get familiar and start building on our platform.