Authentication

All DDS and API calls must be authenticated using a JSON Web Token (JWT). The JWT is a randomly-generated OAuth 2.0 token that should be passed as a Bearer Token in the header of all API calls. You can obtain a JWT by passing your unique AppId and AppSecret, which we provided to you in your "Welcome" package, to the Access Token endpoint described below. Your JWT appears in the response to that call.

Be sure to keep your app ID, app secret, and access token GUIDs secure, as these are used to identify you and your actions in Meevo. The JWT is specific to your integration or app; it not only tells us who you are, it also determines your level of access when calling our endpoints.

JWT validity period

The JWT is valid for an hour from the time the request for a token is received. When a token expires, you will need to make a call for another randomly-generated JWT. Calls sent with expired tokens will receive responses with a 401 Status (Token Exception).

The system will not proactively notify you that a token expired, so take note of the time that you received the response, as well as the value of the expires_in field in the response, and prepare your code accordingly to renew any expired JWTs.

Session patching (changing locations)

JWTs are location-specific. When you change locations within a tenant, the system will issue a new JWT specific to that new location. To prevent repeated authorization calls or session patch calls when switching between locations, MSI recommends caching each token you receive and ensuring that the cache expiration matches expiration of the token.

Requesting your access token (JWT)   

To request a token, POST to the endpoint below making sure to pass your AppId and AppSecret in the body of the call (not as query parameters). Each time you make this call, you'll receive a new, updated token, and the validity counter will be reset.

Auth endpoint

POST  {{MarketplaceURL}}/oauth2/token  

In the body of call, pass the following keys:

"client_id":"AppId",

"client_secret":"AppSecret"

Example call

This example uses the Test Bed Marketplace URL (https://d18devmarketplace.meevodev.com). When your solution or app goes live, you will use the Production Marketplace URL.

POST  https://d18devmarketplace.meevodev.com/oauth2/token

Body of call:

"client_id":"12881",

"client_secret":"1a2B3R"

Example response    

The response body includes your access token, the token type, how long the token is valid for, and a baked-in scope for the token.

{ 
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "meevo:data,meevo:data:cdc:request,meevo:public"
}

Field Name	Definition
access_token	Use this token in the header for authenticating all of your requests. Your access token GUID will be much longer than the one in the example above.
token_type	The JWT is a bearer token.
expires_in	This is the number of seconds that the token is valid. The countdown starts when the response is sent.
scope	Scope is baked-in according to your AppId.

Example response when token is expired

Requests made with an expired token will receive a response with a 401 Status, similar to the following:

{
    "tenantId": 11,
    "locationId": 9,
    "referenceId": "36fc3ace-8f34-43e4-baff-ad93fe254394",
    "error": {
        "errorCode": "TokenException",
        "message": "Token has expired"
    }
}

Updating an expired access token (JWT)

To update your expired access token, make the same call you made when obtaining the original token and replace the token in the header of all calls.