Data Isolation

Use unique, user-specific ApiSessionKeys to limit API data access

The dialogportal™ REST API Data Isolation security feature locks down data access, allowing authenticated entities (users) access to only their own data, and that of contract-defined relations such as parents and children. Once Data Isolation is enabled for an application, all API requests will require a valid ApiSessionKey, and the request will be validated against the entity associated with the ApiSessionKey.

A new ApiSessionKey is generated and returned as an HTTP header from successful Authenticate and Create account requests (plus Register mobile device in certain situations - see Pre-authenticated sessions). The ApiSessionKey is associated with the entity that was authenticated or created, as well as the authenticated application.

Each subsequent API request requires the ApiSessionKey to be included - either as a request header, or as a URL parameter:

Table of Contents

HTTP Header

ApiSessionKey: 1bfl0nx20c7yto1wmytig03yo

URL Parameter

https://api.dialogportal.com/v1/user/dp-key/123/data?ApiSessionKey=esrpwtb17k4o9lpmcfhheabtd

Authentication failure

When Data Isolation is enabled but the ApiSessionKey is missing, incorrect or expired, the request will fail with a 403: Authentication failed response, with a descriptive ApiStatusSubCode:

ApiStatusSubCode	Meaning
403.21	The 'ApiSessionKey' header was missing
403.22	The 'ApiSessionKey' header was not recognised
403.23	The ApiSession session is expired
403.25	Access denied. The ApiSession does not have access to this resource

Configuration

The following settings can be configured depending on how the application is used:

Timeout

The ApiSessionKey will expire after a given Timeout period. The default Timeout is 3 months, but can be as little as 1 hour.

Note that the Timeout is counted from the last time the ApiSessionKey was used, so when the Timeout is 3 months and the ApiSessionKey is accessed every month or 2, the ApiSessionKey will never expire.

Relationships

By default the entity associated with the ApiSessionKey will only have access to its own data. However it is also possible to allow access to other entities, depending on their relationship with the authenticated entity - for example, parent and child entities.

Partner applications (AppKeys) By default, an ApiSessionKey can only be accessed by a request with the same authenticated application (AppKey) that created it. However, if you have multiple applications which work together, the contract can be configured to allow ApiSessionKeys from other applications. This means ApiSessionKeys can be passed from one application to another, removing the need for multiple logins.

Pre-authenticated sessions

When Data Isolation is to be enabled for an application that is already in use, it may not be desirable to have all users log in again with the Authenticate endpoint. In this case Fluid-Solutions can "pre-authenticate" entities, allowing an ApiSessionKey to be generated for them without requiring further authentication.

To retrieve the new ApiSessionKey for pre-authenticated entities, the Register mobile device endpoint is requested, sending ApiSessionKey value "PREAUTHENTICATED" in place of the usual ApiSessionKey (as an HTTP header or URL parameter).

Note that pre-authentication allows only one-time access. Once the pre-authentication has been used, subsequent attempts will result in a standard 403 response, with ApiStatusSubCode 403.22, and the only way to get a new ApiSessionKey is by using the Authenticate endpoint.

Multi-entity endpoints

When Data Isolation is enabled, multi-entity endpoints such as 1011: Search or 1013: Get changed since will always fail with a 403: Authentication failed response, with ApiStatusSubCode 403.25.