Session

Overview

Each data exchange is executed within context of a session. Session provides context for data exchange as well as additional control of Scoping and Limits for given data exchange. This page describes their semantics.

They can be provided with Authorization request

Scope

If you only want to retrieve a subset of data that your contract allows, then setting the CAScope parameter when establishing the session will allow you to filter user data by time range, service group, service or object type. Note, the data you request is limited by your contract, so scoping can only allow you to filter on the maximum amount of data your contract allows.

Parameter	Required	Description	Type
serviceGroups	No	Filter the request based on the service group, service or object type. For more information on how they are related and what services are on offer, please check out the developer documentation.	ServiceGroup[]
timeRanges	No	Filter the data request based on time.	TimeRange[]

TimeRange

Parameter	Required	Description	Type
from	No	This is the unix timestamp in seconds. If this is set, we will return data created after this timestamp.	number
to	No	This is the unix timestamp in seconds. If this is set, we will return data created before this timestamp.	number
last	No	You can set a dynamic time range based on the current date. The string is in the format of <value><unit> For units we currently accept d - day m - month y - year. For example to return data for the last six months : "6m".	string

ServiceGroup

Parameter	Required	Description	Type
id	Yes	This is id of the service group you wish to filter by.	number
serviceTypes	Yes	This contains all the services you want to filter by.	Service[]

Service

Parameter	Required	Description	Type
id	Yes	This is id of the service you wish to filter by.	number
serviceObjectTypes	Yes	This contains all the service objects you want to filter by.	ServiceObject[]

ServiceObject

Parameter	Required	Description	Type
id	Yes	This is id of the service object you wish to filter by.	number

Scoping Examples

In this section, we will give a few examples of how to use scoping to control the amount of data we request from the user.

To only receive Media and Posts from Instagram and Twitter in the last year

{
  "serviceGroups": [{
    "id": 1,
    "serviceTypes": [{
        "id": 3,
        "serviceObjectTypes": [{
            "id": 1
          },
          {
            "id": 2
          }
        ]
      },
      {
        "id": 4,
        "serviceObjectTypes": [{
            "id": 1
          },
          {
            "id": 2
          }
        ]
      }
    ]
  }],
  "timeRanges": [{
    "last": "1y"
  }]
}

To only receive Play History from Spotify in the last month

{
  "serviceGroups": [{
    "id": 5,
    "serviceTypes": [{
      "id": 19,
      "serviceObjectTypes": [{
        "id": 406
      }]
    }]
  }],
  "timeRanges": [{
    "last": "1m"
  }]
}

Limit

If you don't want to wait too long for new data to be fetched, then setting Limit parameter in when stablishing the session will allow you to specify how much user time in your flow your are willing to dedicate to fetching latest data.

Example:

{
  limits: {
    duration: {
      sourceFetch: <seconds>
    }
}

---

Sample Requests

curl --location --request POST 'https://api.digi.me/v1.5/permission-access/session' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "appId": "9v9QKHMbUZglVvjJFRELAPFLSHGQarF3",
    "contractId": "tGouNmYgicUQoa7TYU9nNFYCnrLdVMbM"
}'