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:
ApiSessionKey: 1bfl0nx20c7yto1wmytig03yo
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, |
| 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 Express 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.