Entitlements API Reference

Defining some concepts

Entitlements

Entitlements are any type of content that a user might want to access, for example:

  • eEdition Access (code: eedition)

  • iPad App (code: ipad) 

  • Benefits (code: benefits) 

  • Rewards (code: rewards)

If you are using Naviga's mobile apps please find the info here on how to setup entitlement.

Access Levels

Access Levels illustrate a subscription position to a given Entitlement, for example:

  • Premium: You are entitled to access content.

  • Upgrade: You are not entitled to access content but you can upgrade your subscription to get access.

  • Purchase: You are not entitled to access content and you cannot upgrade your subscription. You need purchase a new one instead.

Household Subscription Levels

To determine access to a specific Entitlement, each Subscription is coded with a “Household Subscription Level”, which is a numeric value that it’s used to calculate its access level.

Integration Points

Access page

What is this?

The Access page is a central place where the users can land from different web pages, so they can be redirected to different sites depending on their access level and the Entitlement they are trying to access to.

If the user is logged-in, an authorization process is carried out behind the scenes followed by a redirect.

In contrast, if the user is not logged-in, the Access page shows up for the user, exposing different actions the user can do, like starting a login process, a new subscription purchase, a new registration flow, an existing subscription activation, etc.

Requirements

The Access page needs to receive two query string parameters to operate:

  • EntitlementCode: It’s the code that identifies the Entitlement.

  • SiteCode: It’s the code that identifies the publication the user is willing to access.

Each Entitlement might be linked to one or any many publications. Settings such as URLs, credentials, etc. are based on that combination.

In both scenarios, if the parameter is not provided, the Access page will use a default value which might cause undesired behaviors.

The possible values for each parameter will be provided in a separated client implementation document.

Subscribe API

What is this?

The Subscribe API is a centralized API used across every Naviga Client, not only for our applications but client’s applications. Among its functionalities, it exposes endpoints to handle Users and Entitlements.

Requirements

The Subscribe API needs to receive five header parameters to operate:

  • X-MediaGroupCode, X-ClientCode, X-PaperCode: Three parameters used by the API to identify the tenant to use.

  • X-SourceSystem: The string used to identify who the consumer is.

  • Authorization: JSON web token used for security purposes.

  • X-CallerId: Customer Registration Id that belongs to the user that triggers the action - optional parameter

Every parameter listed above is a required field, except X-CallerId is optional.

Note: These parameter values will be provided in a separated client implementation document.

Integration Types

Full Subscribe API

This is our recommended option if the Entitlement website/application wants to handle authentication (via the Authentication System) and authorization (via the Subscribe API) processes.

In this case, the user authentication ticket value and expiration will be managed on the Entitlement end.

Note: If Naviga is the Authentication System, the integration point is also the Subscribe API.

Deployment Diagram

Use Cases

Use Case 1 (Non-Logged-In user wants to access content)

Pre-Conditions

  • The user is in a logged-out state in the Entitlement website/app.

  • The user has at least one subscription linked in Subscriber Concierge.

Flow

  1. The User enters the Entitlement website/app.

  2. The Entitlement website/app asks the user to login. Note: The login process might vary depending on the Authentication System that the client is integrated to.

  3. The User enters their credentials and finish the login process. Note: Remember that if the Authentication System is Naviga, Subscribe API has the necessary endpoints to perform the Authentication.

  4. The Entitlement website/app creates an authentication ticket on their end by using User ID.

  5. The Entitlement website/app checks their access level through Subscribe API (Digital Access endpoint) with User ID and Code.

  6. Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.

  7. The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.

Use Case 2 (Logged-In user wants to access content)

Pre-Conditions

  • The user is in a logged-in state in the Entitlement website/app.

  • The user has at least one subscription linked in Subscriber Concierge.

Flow

  1. The User enters the Entitlement website/app. Entitlement

  2. The Entitlement website/app recognizes the user is already logged-in.

  3. The Entitlement website/app checks their access level through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.

  4. Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.

  5. The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.

Use Case 3 (User wants to access web content from eNotify)

Pre-Conditions

  • The user has received an eNotify Email.

  • The user has at least one subscription linked in Subscriber Concierge.

Flow

  1. The User their mailbox and reads eNotify email. Note: Naviga sends daily emails (eNotify) to subscribers to access their Entitlements.

  2. eNotify email will contain a link to redirect the user to the Entitlement website. Note: In the case the Entitlement website allows it, eNotify could pass UserID and Entitlement Code via Querystring. E.g. https://[EDITIONLINK]/?EntitlementCode=[ABCDEF]&custregid=[XXXXXXXX]

  3. The User clicks the eNotify link and gets redirected to the Entitlement website.

  4. The Entitlement website recognizes the user by… A. QueryString parameters provided by Naviga: Go to step #5. B. Previously created authentication ticket: Go to step #5. Note: If the user cannot be authenticated, the website needs to ask the user to login.

  5. The Entitlement website checks their access level through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.

  6. Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.

  7. The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.

Hybrid (Access Page + Subscribe API)

For those scenarios where the Entitlement website/application cannot handle user management flows, you can rely on our Access page which is capable to authenticate and authorize users (the authentication ticket value and expiration will be managed between Naviga and the Authentication System).

After performing an authentication and authorization process successfully, the Access page returns a token that should be stored on the Entitlement end for future Access verification via the Subscribe API.

Deployment Diagram

Use cases

Use Case 1 (User enters wants to access content – NO token)

Pre-Conditions

  • The user has at least one subscription linked in Subscriber Concierge.

  • The user doesn’t have a token in the Entitlement website/app.

Flow

  1. The User enters the Entitlement website/app.

  2. The User gets redirected to the Access page because it doesn’t have any generated token previously. Note: Access page needs to receive the proper Entitlement Code via QueryString otherwise it would use a default one.

  3. The Access page asks the user to log in. Note: If the user is already logged in, it goes to Step #5 directly.

  4. The User enters their credentials and finish the login process.

  5. The Access page checks their access level for the given Entitlement through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.

  6. Subscribe API returns Access level (See section Access Levels in Defining some concepts) and token. Also, if Access level = Premium, it creates an Access event.

  7. The Access page analyzes the response and, only if the access level is Premium, it redirects the user to Entitlement website, using the token as a QueryString parameter.

  8. The Entitlement website stores the token for future verification and displays content to user.

Use Case 2 (User enters wants to access content – Valid token)

Pre-Conditions

  • The user has at least one subscription linked in Subscriber Concierge.

  • The user does have a valid token in the Entitlement website/app.

Flow

  1. The User enters the Entitlement website/app.

  2. The Entitlement site calls Subscribe API (DigitalAccess/token endpoint) sending the token.

  3. Subscribe API indicates whether the user is authorized. If so, it also creates an Access event.

  4. The Entitlement Site displays content to the user.

Use Case 3 (User enters wants to access content – Invalid/Expired token)

Pre-Conditions

  • The user has at least one subscription linked in Subscriber Concierge.

  • The user have an invalid/expired token in the Entitlement website/app.

Flow

  1. The User enters the Entitlement website/app.

  2. The Entitlement site calls Subscribe API (DigitalAccess/token endpoint) sending the token.

  3. Subscribe API returns the user is not authorized.

  4. The Entitlement site redirects the User to the Access page to generate a new token. (Use case 1, Step 2).

Use Case 4 (User wants to access web content from eNotify)

Pre-Conditions

  • The user has received an eNotify Email.

  • The user has at least one subscription linked in Subscriber Concierge.

Flow

  1. The User their mailbox and reads eNotify email. Note: Naviga sends daily emails (eNotify) to subscribers to access their Entitlements.

  2. eNotify email will contain a link to redirect the user to the Naviga Access Page.

  3. The User clicks the eNotify link and gets redirected to the Naviga Access Page. (Use Case 1, Step 2)

Technical Specs

Access Page

The access page could receive multiple query string parameters.

Note: To avoid any kind of issues, please make sure you use URL Encode on every parameter.

Required parameters

EntitlementCode: The code that identifies the Entitlement. (See section “Defining some concepts” for more information). Alphanumeric.

SiteCode: The code that identifies the publication the user is willing to access. Alphanumeric.

URL example: https://myNavigaURL.com/Access?EntitlementCode=eEdition&SiteCode=NAV

Optional parameters

FromURL: The URL the user should be redirected after the authorization process, instead of the URL provided by the Subscribe API.

Mode: The mode the Update Subscription page should load with if the user has Access Level = Upgrade. Possible values:

  • Add: The page will provide products to add to the subscription.

  • Up: The page will provide different offers to change the subscription.

PID: The promotion ID that will be sent as a part of the URL for Subscription Panel (Purchase flow)

ZipCode: The Zip Code that will be sent as a part of the URL for Subscription Panel (Purchase flow)

Subscribe API

Authorize Digital Access

This is the most important endpoint for this integration. It evaluates whether a user has access to Entitlement content.

Request

Method

URL

POST

/DigitalAccess

Type

Params

Values

Required?

HEAD

HEAD

HEAD

HEAD

HEAD

HEAD

BODY

BODY

BODY

X-MediaGroupCode

X-ClientCode

X-PaperCode

Authorization

X-SourceSystem

X-CallerId

CustomerRegistrationId

EntitlementCode

Device

string

string

string

string

string

string

string

string

string

yes

yes

yes

yes

yes

yes

yes

Yes

yes

CustomerRegistrationId: User ID returned by the Authentication System.

EntitlementCode: Code that identifies the entitlement.

Device: User Agent of the device the user is using to access content.

Response

Status

Response

200

{

"Code": 0,

"Errors": [

{

"Message": "string",

"Code": "string",

"Type": {

"Id": 0,

"Code": "string"

},

"ErrorSource": "string"

}

],

"Result": {

"IsAuthorized": true,

"eEditionUrl": "string",

"AccessLevel": "string",

"Token": "string"

}

}

400

{"error":"Authorization is missing."}

400

{"error":"X-SourceSystem is missing."}

400

{"error":"request cannot be null."}

401

{"error":"Invalid X-AuthToken."}

401

{"error":"Invalid X-SourceSystem."}

500

{"error":"Something went wrong. Please try again later."}

Authorize Token

Only used in Hybrid Approach. It verifies whether the token generated by Naviga Access page is still valid.

Request

Method

URL

POST

/DigitalAccess/Token

Type

Params

Values

Required?

HEAD

HEAD

HEAD

HEAD

HEAD

HEAD

BODY

X-MediaGroupCode

X-ClientCode

X-PaperCode

Authorization

X-SourceSystem

X-CallerId

Token

string

string

string

string

string

string

string

yes

yes

yes

yes

yes

yes

yes

Token: Token created on an Entitlement Access authorization.

Response

Status

Response

200

{ "Code": 0, "Errors": [ { "Code": "string", "Message": "string" } ], "Result": { "IsAuthorized": true } }

400

{"error":"Authorization is missing."}

400

{"error":"X-SourceSystem is missing."}

400

{"error":"request cannot be null."}

401

{"error":"Invalid X-AuthToken."}

401

{"error":"Invalid X-SourceSystem."}

500

{"error":"Something went wrong. Please try again later."}

Authenticate User 

Authenticates the user in the proper Authentication System and returns the data necessary to create the proper cookies. 

Request 

Method

URL

POST

/Authenticate

Type

Params

Values

Required?

HEAD

HEAD

HEAD

HEAD

HEAD

HEAD

BODY

BODY

X-MediaGroupCode

X-ClientCode

X-PaperCode

Authorization

X-SourceSystem

X-CallerId

LoginName

Password

string

string

string

string

string

string

string

string

yes

yes

yes

yes

yes

yes

yes

yes

LoginName: Login name or email of the user. 

Password: User’s password. 

Response

Status

Response

200

{ 

  "Code": 0, 

  "Errors": [ 

    { 

      "Message": "string", 

      "Code": "string", 

      "Type": { 

        "Id": 0, 

        "Code": "string" 

      }, 

      "ErrorSource": "string" 

    } 

  ], 

  "Result": { 

    "Authenticated": true, 

    "CookieContent": [ 

      { 

        "Name": "string", 

        "Content": "string" 

      } 

    ], 

    "CustomerRegistrationId": "string", 

    "EncryptedCustomerRegistrationId": "string" 

  } 

} 

400

{"error":"Authorization is missing."}

400

{"error":"X-SourceSystem is missing."}

400

{"error":"request cannot be null."}

401

{"error":"Invalid X-AuthToken."}

401

{"error":"Invalid X-SourceSystem."}

500

{"error":"Something went wrong. Please try again later."}

Initiate Forgot Password

Sends an email to the user with a link to reset the password.

Request

Method

URL

POST

/ForgotPassword

Type

Params

Values

Required?

HEAD

HEAD

HEAD

HEAD

HEAD

HEAD

BODY

BODY

X-MediaGroupCode

X-ClientCode

X-PaperCode

Authorization

X-SourceSystem

X-CallerId

LoginName

ReturnUrl

string

string

string

string

string

string

string

string

yes

yes

yes

yes

yes

yes

yes

yes

LoginName: Login name or email of the user.

ReturnURL: Where the user has to be redirected after the password is changed.

Response

Status

Response

200

Response will be an object containing the list of users

{ "Code": 0, "Errors": [ { "Message": "string", "Code": "string", "Type": { "Id": 0, "Code": "string" } } ], "Result": { "PasswordResetLinkSent": true } }

400

{"error":"Authorization is missing."}

400

{"error":"X-SourceSystem is missing."}

400

{"error":"request cannot be null."}

401

{"error":"Invalid Authorization."}

401

{"error":"Invalid X-SourceSystem."}

500

{"error":"Something went wrong. Please try again later."}

PreviousSubscription APINextFirefly

Last updated