A right works much like a ticket. Rights are granted to users and allow access to a service, parts of a service or a combination of both. There is no restrictions on how the rights are used; the implementation is completely up to the service provider.

Rights are closely tied in with the Service Catalog. The SKUs used when creating rights must be of an existing entry in the Service Catalog.

Creating rights

There are two ways of creating a right

  • Directly through the Rights resource described on this page

  • Indirectly through subscriptions described on the subscriptions page.

In most cases using a right directly is the easiest way to use rights; if you want to grant access on a more or less perpetual basis (e.g. a freemium style right) you can create a right with a very long time span. If you want to provide a prepaid subscription service where the customer might cancel at any time a subscription might be the best choice.

Right states

Rights can be in several states: CREATED, ACTIVE, SUSPENDED and EXPIRED. The initial state is CREATED. Once a right is created it can change state to ACTIVE or SUSPENDED. After the time interval on the right passes, the state may change to EXPIRED. An expired right is not longer to be considered valid.

The used flag on the right can be set whenever the right is active. A right can not move from used to unused.

It is the responsibility of the service provider to check if the user has the necessary rights to run the service. Changes in rights generates events which are distributed through the Event Queue.

Right objects

The right object contains the following fields:

  • rightId: The right ID. This is an alphanumeric identifier unique for every right.

  • generation: The generation counter. This field changes whenever the right is updated. This field can be used for optimistic concurrency control.

  • href: This is a reference to the resource itself.

  • state: The state of the right.

  • userId: The CONNECT ID for the user owning the right.

  • link: A set of links to related resources. self points to the right itself, user points to the CONNECT user owning the right, use points to the usage endpoint and suspend which is used to suspend the right.

  • grantorId: The grantor ID of the one that created the right.

  • grantorContext: A context string used by the grantor. Unless you are the grantor you should not make assumptions on the content of this field.

  • serviceProviderId: If the service provider ID is different from the grantor ID this field is set to the relevant service provider ID.

  • timeInterval: The interval the right will be active. The format is according to ISO 8601.

  • sku: Stock-keeping unit The SKUs are defined in the Service Catalog.

  • payload:

  • used: The used flag. A right can either be unused or used. It is the responsibility of the service provider to flag rights as used whenever the users of the service consume the rights.

  • active: This is a convenience flag that is set to true if the right is active, taking into account the current value of state, as well as the current time.

    {
      "rightId": "52fb",
      "generation": "52fd",
      "href": "https://api.telenor.io/id/users/5479/rights/52fb",
      "state": "ACTIVE",
      "userId": "5479",
      "link": [
        {
          "rel": "user",
          "href": "https://api.telenor.io/id/users/5479",
          "type": null,
          "idref": null
        },
        {
          "rel": "self",
          "href": "https://api.telenor.io/id/users/5479/rights/52fb",
          "type": null,
          "idref": null
        },
        {
          "rel": "use",
          "href": "https://api.telenor.io/id/users/5479/rights/52fb/usage",
          "type": null,
          "idref": null
        },
        {
          "rel": "suspend",
          "href": "https://api.telenor.io/id/users/5479/rights/52fb/suspend",
          "type": "action",
          "idref": null
        }
      ],
      "grantorId": "NETLIFE_B2C",
      "grantorContext": "Freemium right added by Netlife",
      "serviceProviderId": null,
      "timeInterval": "2015-03-06T00:00:00.000Z/2114-03-06T00:00:00.000Z",
      "sku": "CMO-STO-2-FREE",
      "payload": null,
      "used": true,
      "active": true
    }

Access to the user rights to consume services in a certain time period.

Rights 

Right list 

List rights
/id/users/{connectId}/rights{?grantorId,active}

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

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    grantorId
    string (optional) 

    Optional Grantor ID to filter rights on

    active
    datetime (optional) 

    Optional datetime string filtering on rights active at the given time. Note that this only considers the currently active rights.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The list of rights on the given CONNECT ID user is returned. The array right contains a list of the active and inactive rights on the user.

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

  • Response  401
  • You do not have access to the specified right collection. For Basic authentication, if you specify another grantorId parameter than your current association, you’ll get this status code, but another WWW-Authenticate challenge.

    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 CONNECT ID specified can’t be found.

    Headers
    Content-Type: text/html

Create right 

Create right
/id/users/{connectId}/rights

Create right

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

  • Request
  • The simplest create request contains the fields sku, grantorId and timeInterval. If the state field is omitted it will be created with the default state (CREATED). The grantorContext field, although optional, is also useful on creation, to provide some kind of reference back into the grantor’s external system.

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "sku": "SOME_SKU",
      "grantorId": "<grantorId>",
      "grantorContext": "<grantor specific context>",
      "timeInterval": "<ISO 8601 time interval>"
    }
  • Response  201
  • Right is created. A right object is returned.

    Headers
    Content-Type: application/json
    Body
    { <right object> }
    
  • Response  400
  • There was an error creating the right; either one of the required fields are missing or there is an error in one of the fields. The error message specifies what the error is.

    Headers
    Content-Type: text/plain
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT ID user specified can’t be found.

    Headers
    Content-Type: text/html

Right resource 

Retrieve right
/id/users/{connectId}/rights/{rightId}

Retrieve a single right on a CONNECT user.

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

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    rightId
    string (required) 

    The right ID.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The returned right object is as described in the introduction.

    Headers
    Content-Type: application/json
    Body
    { <right 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 CONNECT ID user or right can not be found.

    Headers
    Content-Type: text/html
Remove right
/id/users/{connectId}/rights/{rightId}

Remove the right from CONNECT ID user.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    rightId
    string (required) 

    The right ID.

  • Request
  • Headers
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The right has been removed from the CONNECT user.

  • Response  401
  • You do not have permission to remove the right. A right can only be removed by an administrator or the grantor that created it.

    Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The specified right or CONNECT ID can not be found.

    Headers
    Content-Type: text/html

Suspend right 

/id/users/{connectId}/rights/{rightId}/suspend
  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    rightId
    string (required) 

    The right ID.

  • Request
  • Headers
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The right has been suspended.

  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The specified right or CONNECT ID can not be found.

    Headers
    Content-Type: text/html

Activate right 

/id/users/{connectId}/rights/{rightId}/activate
  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    rightId
    string (required) 

    The right ID.

  • Request
  • Headers
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The right has been activated.

  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The specified right or CONNECT ID can not be found.

    Headers
    Content-Type: text/html

Record usage 

/id/users/{connectId}/rights/{rightId}/usage

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

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID.

    rightId
    string (required) 

    The right ID.

  • Request
  • Headers
    Authorization: Bearer <access token>
  • Response  204
  • Usage is recorded on the right. This might cause a ServiceAnnounce event to be sent to the Event Queue, depending on the configuration in the Service Catalog.

  • 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 specified right or CONNECT ID can not be found.

    Headers
    Content-Type: text/html

© 2017 Telenor Digital AS