Add a New Subscription

Use this endpoint to add a new subscription to the subscription service.

Both the requester and the subscriber listed in the posted subscription must have permissions granted to the item to which they are subscribing.

URL

https://api.digitalvault.cloud/subscription

Method

POST

Required IMS Scopes

subscription_write

Request Header Parameters

Property Description
Authentication Bearer {access_token}
required		 Retrieve access token

Request Body Params

Property Description
subscriber Principal to list as subscriber in prefixed-principal notation
source JObject representing the resource to subscribe to

Source

Property Description
type One of: Device, Timeseries
id For Device, {{DEVICE_ID}}. For Timeseries, {{TIMESERIES_ID}}:{{METRIC_NAME}}

Response Body Parameters

Name Description
id A unique identifier representing the created subscription
type One of: Device, Timeseries
id For Device, {{DEVICE_ID}}. For Timeseries, {{TIMESERIES_ID}}:{{METRIC_NAME}}

Errors

Error Description
400 Subscription post attempted is invalid
401 Unauthorized
403 Forbiden. Possible causes:
You do not have access to this endpoint (scope)
 You do not have access to the source
* The subscriber does not have access to the source
409 Subscriber is already subscribed to source

Example

Request

POST https://api.digitalvault.cloud/subscription
{
    "subscriber": "sub:app:testApp1",
    "source":
    {
        "type": "Device",
        "id": "subscriptionDevTest1"
    }
}

Response

{
    "subscriber": "sub:app:testApp1",
    "source":
    {
        "type": "Device",
        "id": "subscriptionDevTest1"
    }
}

Notes

  • Use the following formats to define the subscriber:
    • User = ‘sub:user:{{USERID}}’
    • Application: ‘sub:app:{{APPID}}’