A subscription is very similar to a regular newspaper subscription; it is a mechanism to generate new rights at fixed intervals. Do note that subscriptions are not the same as rights; a subscription is merely a right generator so creating a subscription is not the same as creating a right. Also note that rights can be removed so if you want to grant access to a service through a right you might not need to create a subscription at all; a single right with a very long expiry will in most cases do the trick. Likewise; if you want to time limit the access you can set the expire time for the right itself.

The canonical example of a service that uses the subscription API is someone providing pre-paid periodic subscriptions like Netflix, Spotify or a newspaper. Since the rights are created up front you can remove the subscription at any time but the customer will still have the rights associated with the service, i.e. the period for which the customer has been billed.

Subscriptions can be in three different states:

  • Active - this is the default state for subscriptions. When a new period starts one or more rights are generated by the subscription.

  • Suspended - when the subscription is suspended it will still generate rights but they will be generated in a suspended state. A subscription can be suspended and activated at any time but please note that a subscription that has been activated won’t activate any of the old rights; the net result is that the customer won’t receive a right until the subscription is renewed.

  • Expired - when the subscription expires it won’t generate any more rights. You can not reactivate an expired subscription. Subscriptions are automatically set to expired when they end.

The general rule of thumb is that you will only have access to the subscriptions you have created as a grantor. Service providers won’t interact with the subscriptions, only with the rights.

Subscription objects

The subscription object contains the following fields:

  • subscriptionId string

    The subscription ID. This is an alphanumeric identifier unique for all subscriptions.

  • href string

    A reference to the resource itself.

  • generation string

    The generation for the subscription. This can be used for optimistic concurrency control.

  • state string

    The state of the subscription.

  • userId string

    The CONNECT ID for the user.

  • link array

    A set of links to related resources. This includes links to self (a direct reference to the resource representing the subscription), suspend/activate (the resource to suspend or activate the subscription) and user - the user that the subscription belongs to.

  • grantorId string

    The grantor ID of the grantor that has created the subscription.

  • rightsSpec array

    An array of right templates which will be used when rights are generated.

  • origTimeSpec ISO 8601 string

    The original time spec field for the subscription.

    {
      "subscriptionId": "5150",
      "href": "https://api.telenor.io/id/users/5479/subs/5150",
      "generation": "52fa",
      "state": "ACTIVE",
      "userId": "5479",
      "link": [
        {
          "rel": "self",
          "href": "https://api.telenor.io/id/users/5479/subs/5150",
          "type": null,
          "idref": null
        },
        {
          "rel": "suspend",
          "href": "https://api.telenor.io/id/users/5479/subs/5150/suspend",
          "type": "action",
          "idref": null
        },
        {
          "rel": "user",
          "href": "https://api.telenor.io/id/users/5479",
          "type": null,
          "idref": null
        }
      ],
      "grantorId": "GRANTOR_ID",
      "grantorContext": "17833",
      "rightsSpec": [
        {
          "serviceProviderId": null,
          "timeSpec": null,
          "sku": "SOME_SKU",
          "grantorContext": null
        }
      ],
      "origTimeSpec": "R/2014-02-05T09:35:39.184+01:00/P1M",
    }

Right templates

When generating rights the rightSpec structures are used to create new rights. Each entry represents a new right so if you want to create more than one right when the subscription is renewed, add two objects in the list.

{ “serviceProviderId”: “{serviceProviderId}”, “timeSpec”: “P1W”, “sku”: “SOME_SKU”, “grantorContext”: "" }

The fields are described in detail in the rights documentation.

Subscriptions 

List subscriptions 

/id/users/{connectId}/subs{?grantorid}

List subscriptions on a CONNECT user, optionally filtering on who is the grantor.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.sub.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    grantorid
    string (optional) 

    Your grantor ID. Return just the subscriptions granted by the specified grantor.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The request has successfully completed and the list of subscriptions stored on the CONNECT ID user is returned. The result is returned as an array named subscription. Each element is a separate subscription.

    Headers
    Content-Type: application/json
    Body
    {
      "subscription": [
        { <subscription object > },
        { <subscription object > }
      ]
    }
  • Response  307
  • Unless you have administrative access you must specify the grantor ID when querying the subscriptions. If you attempt to retrieve all subscriptions (i.e. do not specify the grantorid parameter) you will be redirected to the proper URL.

  • Response  401
  • You do not have access to subscriptions.

    Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • The specified subscription and/or CONNECT user does not exist.

    Headers
    Content-Type: text/html

Create new subscription 

Create new subscription
/id/users/{connectId}/subs

Create a new subscription.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

  • Request
  • The JSON structure may contain the following fields:

    • grantorId (required): The grantor ID to be used when creating the rights.

    • timeSpec (required): The start and stop time for the subscription.

    • rightsSpec (required): An array of right specifications (or templates) for the rights. The specification is an array of right specification templates. Each template generates a new right. Each template has the following fields:

      • sku (required): The SKU to use when creating rights.
      • serviceProviderId (optional): The service provider ID to use.
      • timeSpec (optional): The time spec to use when creating new rights.
      • grantorContext (optional): A string that can be used to reference internal systems. Note that this context will be the same for all rights created by the subscription.
    • state: The initial state of the subscription. The default for this is ACTIVE. Permitted states are ACTIVE and SUSPENDED.

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "grantorId": "MY_GRANTOR_ID",
      "state": "ACTIVE",
      "rightsSpec": [
        {
          "serviceProviderId": "{serviceProviderId}",
          "timeSpec": "P1W",
          "sku": "SOME_SKU",
          "grantorContext": "<optional grantor context>"
        }
      ],
      "timeSpec": "R/2015-01-01/2015-31-12/P1W"
      "paymentAgreement": "<the agreement to use>"
    }
  • Response  201
  • The subscription is created. The returned JSON structure contains the complete subscription.

    Headers
    Content-Type: application/json
    Body
    <subscription object as described above>
  • Response  400
  • If one or more required fields in the request body are missing or if your request body is malformed you’ll get a 400 Bad Request response.

    Headers
    Content-Type: text/plain
    Body
    Plain text error message.
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT ID specified in the request can’t be found.

    Headers
    Content-Type: text/html

Subscription operations 

Retrieve subscription
/id/users/{connectId}/subs/{subscriptionId}

Retrieve a single subscription from the server.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.sub.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    subscriptionId
    string (required) 

    The subscription ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • When successful, a subscription object is returned. See description above.

    Headers
    Content-Type: application/json
    Body
    <subscription as JSON object>
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • The subscription ID and/or CONNECT ID are unknown.

    Headers
    Content-Type: text/html
Delete subscription
/id/users/{connectId}/subs/{subscriptionId}

Remove the subscription. Note that rights created by the subscription will still be present, even if the subscription is removed.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    subscriptionId
    string (required) 

    The subscription ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The subscription has been successfully removed. Note that you’ll get this response for invalid subscriptions as well.

    Headers
    Content-Type: application/json
  • Response  401
  • You are not allowed to remove the specified subscription. Only administrators and API users with a matching grantorId are allowed to remove the subscription.

    Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"

Activate subscription 

/id/users/{connectId}/subs/{subscriptionId}/activate

Activate a suspended subscription. This changes the state from SUSPENDED to ACTIVE and it will start generating rights again. Note that the subscription will only generate future rights, not rights in the past. Any existing suspended rights will be reactived.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    subscriptionId
    string (required) 

    The subscription ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • Subscription is successfully activated.

    Headers
    Content-Type: application/json
  • Response  401
  • You are not allowed to activate the specified subscription. Only administrators and API users with a matching grantorId are allowed to activate and suspend the subscription.

    Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  409
  • The subscription can’t be activated since it is either already active or has expired.

    Headers
    Content-Type: text/plain

Suspend subscription 

/id/users/{connectId}/subs/{subscriptionId}/suspend

Suspend an active subscription. This changes the state from ACTIVE to SUSPENDED and it will stop generating rights. The existing rights will also be suspended.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    subscriptionId
    string (required) 

    The subscription ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • Subscription is successfully deactivated.

    Headers
    Content-Type: application/json
  • Response  401
  • You are not allowed to suspend the specified subscription. Only administrators and API users with a matching grantorId are allowed to activate and suspend the subscription.

    Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  409
  • The subscription can’t be suspended since it is either already suspended or has expired.

    Headers
    Content-Type: text/plain

© 2017 Telenor Digital AS