Technical Summary

Core design principles of the SessionM Platform APIs: authentication, server-to-server communication, message IDs, and generic statuses and errors.

The platform is built on a few core design principles detailed below.

Authentication, Authorization and Security

SessionM APIs operate with state-of-the-art authentication, authorization and security features. The APIs are accessible to engineering and services professionals via server-to-server communication protocols, which allow the platform to unify user actions for improved reporting. HTTP basic authorization protocol is available for server-to-server communication supporting registered users, requiring a username as its application API key and a password as a base64 encoded application secret.

Following is a sample request made via a Curl command:

Example Request

curl --location --request POST
'https://api-tenant1.ent-sessionm.com/priv/v1/apps/{{apikey}}/users' \ 
--header 'Authorization:Basic {{base64 encoded output of apikey:apisecret}}'\ 
--header 'Content-Type:application/json'\ 
--data-raw '{"user":{"email":"foo@bar.com"}}'

Server-to-Server

Server-to-server communications can use either HTTP basic or HTTP bearer authorization protocols. For the basic protocol, each request must contain an API key and server-to-server API secret supplied by the SessionM Platform; for the bearer protocol, each request must contain an authorization token in an HTTP header. All requests must be made over HTTPS.

As an additional security measure, access to APIs lives behind a basic authentication layer and can be additionally IP-restricted to meet the security requirements of specific client needs. These credentials are always required for server-to-server communication with the SessionM Platform.

In order to begin using any server-to-server APIs, the client must first request an API key and server-to-server API Secret issued from the SessionM Platform. For more information, see Before You Begin.

Message IDs

When using the SessionM S2S APIs, it is strongly recommended that the client provide a unique Message ID with each request, as follows:

Example HTTP Request Header

                GET /path/to/api/endpoint HTTP/1.1
                Content-Type: application/json
                Message-ID: de305d54-75b4-431b-adb2-eb6b9e546014

Doing so allows a simple way to track messages and also provides a means for supporting idempotent requests. When a request is sent with a Message ID in its HTTP header, that ID becomes associated with the request. It is included in the HTTP header of the accompanying response and can be used to uniquely identify a message within the SessionM Platform.

A request that is sent with a Message ID lists the message processing date in its response. Also, subsequent requests for the same Message ID made within 30 minutes of the original causes a cached response to be re-sent without producing any new changes in state. Replayed requests like this are marked by the 'Cached-Message' header being set to 'true' in the response, as shown below:

Example HTTP Response Header (Existing Message)

                HTTP/1.1 200 OK
                Content-Type: application/json
                ...
                Message-Id: de305d54-75b4-431b-adb2-eb6b9e546014
                Message-Date: Mon, 28 Sep 2015 03:04:15 GMT
                Cached-Message: true

Generic Statuses and Errors

When an API method runs, one of the following HTTP response status codes is returned:

200 - Indicates successful call; returned string can be either ok or error.
401 - Indicates unsuccessful call; not authorized.
404 - Indicates unsuccessful call; not found by ID.
500 - Indicates internal error associated with SessionM.

Here is an example:

Generic Error Example

{
                "status" : "error",
                "errors" :
                {
                "code" : "requires_registered_user"
                }
            }

When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Consider the generic error example shown in the frame right-hand frame. Returned errors can be either method-specific or generic, which is the case for the error above. Any method-specific errors are documented in their associated API document. However, responses that return generic errors may contain a message from the platform indicating any of the following conditions:

Code	Reason
INTERNAL_SERVER_ERROR	Unexpected SessionM server error occurred.
HTTPS_ONLY	HTTPS protocol is required.
INVALID_AUTH_TOKEN	Token could not be decrypted; or token has expired.
USER_NOT_FOUND	Customer ID or external customer ID not located in the system.
INVALID_API_KEY	Wrong API key passed in.
REQUIRES_REGISTERED_USER	Similar to USER_NOT_FOUND.
MISSING_DATA	Required parameters not passed in.
VALIDATION	This catch-all validation error is returned when there is no specific error code.
ACCESS_DENIED	Authentication credentials passed in were invalid.
NOT_AVAILABLE	Object was found but is unavailable. For example, a campaign not being targeted to a requesting customer.
NOT_FOUND	Object does not exist.
ARGUMENT_ERROR	Unexpected type or format parameter.

For information on responses that return object-specific errors, see the object's dedicated API.

Note: When developing code that integrates with the SessionM platform, organizations can expect that error codes will not change. This principle ensures that development teams can utilize these error codes to create and communicate error messages that make sense for their implementation, or their customers. Alternatively, it's worth noting that the SessionM messages provided with the codes are available.

Was this page helpful?