--- title: "Data Access Guide for Data Recipients" slug: "data-access-guide-for-data-recipients" updated: 2026-07-02T10:22:26Z published: 2026-07-02T10:22:26Z canonical: "learn.servitly.com/data-access-guide-for-data-recipients" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://learn.servitly.com/llms.txt > Use this file to discover all available pages before exploring further. # Data Access Guide for Data Recipients This article describes the standard workflow for a **Data Recipient** to access data shared by customers through the DPS, from authentication to retrieving metrics data. > [!NOTE] > Prerequisite > > - To access customer data, the Data Recipient must be registered and authorized in the DPS by the OEM organization. > - Before making any API request, the Data Recipient must obtain an [*API Key*](/v1/docs/end-user-api-keys) and *a* [*Personal Access Token*](/v1/docs/personal-access-tokens) *(PAT)*. Here are the main steps to access customer data via REST API: - [Authenticate to the DPS backend](/v1/docs/data-access-guide-for-data-recipients#authenticate-to-the-dps-backend) - [Get the list of connected products](/v1/docs/data-access-guide-for-data-recipients#get-the-list-of-connected-products) - [Get the list of metrics](/v1/docs/data-access-guide-for-data-recipients#get-the-list-of-metrics) - Retrieve metric data: - [Get metric historical data](/v1/docs/data-access-guide-for-data-recipients#get-metric-historical-data) - [Get the latest metric values](/v1/docs/data-access-guide-for-data-recipients#get-the-latest-metric-values) ## Get API Key and Personal Access Token Before performing any API request, the Data Recipient must retrieve the API Key and configure a PAT (Personal Access Token) required for the authentication. 1. Access the DPS login page. 2. Authenticate using username/password or Single Sign-On (SSO), if enabled. 3. Navigate to the *Account* page, then to *API Key*, where you can copy the API Key needed to authenticate with an API Client. 4. Navigate to the Profile page and then Security, where it is possible to create a new PAT (Personal Access Token). ## Authenticate to the DPS backend With the API KEY and PAT, you can authenticate to the DPS and obtain a JWT token to perform API requests. RequestResponse ```http POST /api/identity/users/patLogin Host: X-Servitly-Tenant: Content-Type: application/json {  "apiKey": "",  "pat": "" } ``` You must replace: - *BASE_URI*: the base URI where the DPS is published (e.g., [https://connect.acme.com)](https://connect.acme.com)). - *TENANT_NAME*: the name of the tenant (e.g., acme-connect). - *API_KEY*: the API Key copied from the *Account* page. - *PAT*: the PAT created in the *Profile* page. ```http Content-Type: application/json {  "token": "661fd29342541977c4002ec7...",  "tokenExpirationTimestamp": 1578438000000,  "refreshToken": "cd2bd3a0-861d-4798-8fd6-2a2a99fb92e8",  "userId" : "6616689a0de6d87b47cd6308",  "tenantId": "661533a57bba156cf6e8d04b" } ``` In case the login succeeds, the response (`code 200`) contains the token that must be issued as a bearer token in the subsequent requests. ## Get the list of connected products With a token, you can get the list of connected products for which you are authorized to access data. RequestResponse ```http POST /api/v2/identity/users/me/things Host: X-Servitly-Tenant: Authorization: Bearer 661fd29342541977c4002ec7... Content-Type: application/json ``` You must replace: - *BASE_URI*: the base URI where the DPS is published (e.g., [https://connect.acme.com)](https://connect.acme.com)). - *TENANT_NAME*: the name of the tenant (e.g., acme-connect). ```http Content-Type: application/json {  data: [    {      "id": "881583a58bba156cf6e8d04b",      "serialNumber": "SN-0001",      "thingDefinitionId": "33155s56bba156cf6e8d04b",      "productModel": {          "name" : "Model-abc"      }    },    {      "id": "221128a58bba156cf6e8d04b",      "serialNumber": "SN-0002",      "thingDefinitionId": "33155s56bba156cf6e8d04b",      "productModel": {          "name" : "Model-abc"      }    }  ] } ``` For more details about this endpoint, you can refer to this [article](https://learn.servitly.com/apidocs/get-me-things). ## Get the list of metrics With the ID of a thing definition, you can get the list of RAW data metrics from which you can retrieve data. RequestResponse ```http POST /inventory/thingDefinitions//metrics Host: X-Servitly-Tenant: Authorization: Bearer 661fd29342541977c4002ec7... Content-Type: application/json ``` You must replace: - *BASE_URI*: the base URI where the DPS is published (e.g., [https://connect.acme.com)](https://connect.acme.com)). - *TENANT_NAME*: the name of the tenant (e.g., acme-connect). - *THING_DEFINITION_ID*: the ID of the thing definition associated with the thing. ```http Content-Type: application/json {  data: [    {      "id": "112233a58bba156cf6e8d04b",      "name": "int_temp",      "label" : "Internal Temperature"      "description": "The measured internal temperature",      "type" : "FLOAT",      "unit": "°C"    },    {      "id": "1422434s82ba156cf6e8d04b",      "name": "int_hum",      "label" : "Internal Humidity",      "description": "The measured internal humidity",      "type" : "FLOAT",      "unit": "%"    }  ] } ``` For more details about this endpoint, you can refer to this [article](https://learn.servitly.com/apidocs/get-metrics-by-thing-definition). ## Get metric historical data With this endpoint, you can retrieve the values of a metric for a specific thing and a period of time. RequestResponse ```http POST /api/data/values?thingId=&metricName=&startDate=&endDate= Host: X-Servitly-Tenant: Authorization: Bearer 661fd29342541977c4002ec7... Content-Type: application/json ``` You must replace: - *BASE_URI*: the base URI where the DPS is published (e.g., [https://connect.acme.com)](https://connect.acme.com)). - *TENANT_NAME*: the name of the tenant (e.g., acme-connect). - *THING_ID*: the ID of the thing whose data must be retrieved. - METRIC_NAME: the name of the metric whose data must be retrieved. - START_TS: the timestamp (long format) related to the period start time. - END_TS: the timestamp (long format) related to the period end time. If missing, the current timestamp is used. ```http Content-Type: application/json {  data: [     {        "timestamp": 1578438000000,        "values": [           {             "name":  "int_temp",             "value": 26.5           }        ]     }    ] } ``` For more details about this endpoint, you can refer to this [article](https://learn.servitly.com/apidocs/get-thing-metric-value). ## Get the latest metric values With this endpoint, you can retrieve the last received value for multiple metrics of a specific thing. RequestResponse ```http POST /api/data/lastValues?thingId=&metricName= Host: X-Servitly-Tenant: Authorization: Bearer 661fd29342541977c4002ec7... Content-Type: application/json ``` You must replace: - *BASE_URI*: the base URI where the DPS is published (e.g., [https://connect.acme.com)](https://connect.acme.com)). - *TENANT_NAME*: the name of the tenant (e.g., acme-connect). - *THING_ID*: the ID of the thing whose data must be retrieved. - METRIC_NAME: the name of the metric whose data must be retrieved. You can add the same parameter multiple times with different metric names. ```http Content-Type: application/json {  data: [    {                   "name":  "int_temp",       "timestamp": 1578438000000,           "value": 26.5    },    {                   "name":  "int_hum",       "timestamp": 1578437300000,           "value": 45    }    ] } ``` For more details about this endpoint, you can refer to this [article](https://learn.servitly.com/apidocs/get-thing-metrics-last-value). ## Error Codes Here are the error codes you can get when invoking the DPS APIs. | Code | Description | | --- | --- | | 401 | The request could not be processed because the authentication token or login credentials are missing, invalid, or expired. | | 403 | Although the user has been authenticated, the necessary permission to access the requested resource or perform the requested action is missing. | | 404 | The requested resource does not exist. | | 429 | The client has sent too many requests in a given time window and has been temporarily throttled. | | 500 | An unexpected error occurred while processing the request on the server. |