Mental Canvas REST API

A REST API for client apps or web services to interface with Mental Canvas Cloud Service

API Client

The client refers to an app (or a web service) that uses the API. To use the API, you need to get a Mental Canvas developer account, and obtain client_id and client_secret for the app or the service from Mental Canvas. If you have mulitple apps or services, you should obtain a client_id and client_secret for each of them.

API Acess Tokens

All API requests require an access token. You obtain an access token using the OAuth2 Authentication. Once you have an access token, you add it to your API request headers to authenticate the client (your app) and the user making the requests. You need to add the word Bearer in front of the token. You should send the request via HTTPS.

  • Headers
  Authorization: `"Bearer " + access_token`
  (for example, `Bearer 72ab415822b56cf0f9f93f07fe978d9aae859325`)

For example, to get the projects of a user using curl:

curl -X GET "https://api_host/projects" \
  -H "accept: application/json" \
  -H "Authorization: Bearer 82ab415822b56cf0f9f93f07fe978d9aae85932s"

OAuth2 Authentication

The OAuth2 authentication supports two grant types to obtain access tokens:

  • client_credentials: For API calls that do not require user authentication (only require client_id and client_secret).
  • password: For API calls that require the user's signin credentials (username and password) in addition to the client credentials.

Client Credentials Grant

Obtain an access token with the client_credentials grant

You should send a POST request with base64 encoded client credentials in request headers and the grant type in request body. You shoudl keep client_secret confidential and only send the request via HTTPS.

  • Headers
  Authorization: `"Basic " + client_id:client_secret base64'd`
  (for example, to use `application:secret`, you should send `Basic YXBwbGljYXRpb246c2VjcmV0`)
  Content-Type: `application/x-www-form-urlencoded`
  • Body
  `grant_type=client_credentials`

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=client_credentials" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

Password Grant

The password grant should be used when user authentication is required. Any projects uploaded by a user will require user authentication to access and manage them.

Obtain an access token with the password grant

You need to include the client credentials in request headers, and the user credentials and grant type in request body:

Note: For user authentication, client_secret is not required and can be any non-empty string. However, if a valid client_secret is provided, the token can be used for both client and user authentication.

  • Headers
  Authorization: `"Basic " + client_id:client_secret base64'd`
  (for example, to use `application:secret`, you should send `Basic YXBwbGljYXRpb246c2VjcmV0`)
  Content-Type: `application/x-www-form-urlencoded`
  • Body
  `grant_type=password&username=pedro@myemail.com&password=Wsi024R`
  (contains 3 parameters: `grant_type`, `username` and `password`)

The body paramaters should be URL-encoded.

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=password" \
  -d "username=pedro@myemail.com" \
  -d "password=Wsi024R" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

Token Response

The token response body is a JSON message that contains the access token and the expiry time (in seconds.) The access tokens are usually short-lived (e.g. 2 hours.) You can use a long-lived (e.g. 2 weeks) refresh_token to extend their expiry time without asking the user to sign in again. Note that you may not get a refresh token with the client_credentials grant since you can simply request a new access token using client_id and client_secret.

{
  "access_token": "3e952f18916d3abd44b16005f81ca3ccb7eb33ea",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "cbef57f721ad0b5c3931624fc85d9a771b41bdcc"
}

Use refresh tokens to extend token expiry time

If an access token expires, you can use its refresh token to request a new access token with the refresh_token grant.

For example, using curl:

curl https://api_host/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=cbef57f721ad0b5c3931624fc85d9a771b41bdcc" \
  -H "Authorization: Basic YXBwbGljYXRpb246c2VjcmV0" \
  -H "Content-Type: application/x-www-form-urlencoded"

You will get a new access token, a refresh token, and a new token expiration time. You can repeat the process as long as the refresh token has not expired. A refresh token can only be used once to exchange for a new access token with the refresh_token grant.

Concurrent User Sessions [Not Implemented]

The API server has a limit on the number of concurrent sessions per user. Currently, each user is allowed to have up to two non-expiring access_tokens obtained with the password grant. Any additional access_tokens beyond the limit will be automatically invalidated when a new access_token is granted to a user. The limit does not apply to access_tokens obtained with the client_credential grant.

API Test Page

You can see the API documentation and test it at:

Api-test

API Endpoints

  • Prod Server: https://mcrestapi.azurewebsites.net/
  • Dev Server (internal use only): https://mcrestapi-dev.azurewebsites.net/