Entitlement Troubleshooting

The AlphaSense Enterprise Insight platform uses entitlement-ng as the central service for evaluating user access to documents across all content providers — including broker research, expert calls, user-uploaded documents, market research, and RSS feeds. It resolves entitlement by fetching tokens for a given user and document from the relevant provider APIs and checking for overlap. Failures in any underlying provider, misconfigured umbrella users in private cloud environments, or latency breaches in token fetching can all result in users being unable to access documents they are entitled to.

This document serves to outline common failure scenarios related to entitlement-ng and provide troubleshooting steps for resolution.

NOTE: On production environment direct access to application services may not be feasible so please port-forward these service as such.

kubectl port-forward <pod-name> <local-port>:<pod-port> -n applications

Once they are port-forward please modify the curl command with the appropriate port numbers

Failure Scenarios

1. User Cannot Open Some Documents (403 Error in UI)

Triage

A user receives a 403 error in the UI and is unable to open a specific document. The document may appear in search results but clicking it returns an access denied response. This typically indicates that entitlement-ng is returning NONE for the user–document combination, meaning there is no overlap between the user's entitlement tokens and the document's required tokens.

Assumption: Document id(s) are already available from the error logs.

Troubleshooting

Check whether the /v1/entitlement endpoint returns NONE or AVAILABLE for the affected user and document

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/entitlement' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "id": <user-id>
    },
    "documents": [
      {
        "id": "<document-id>"
      }
    ]
  }'

If the response is NONE, check tokens for the user and for the document separately to identify which side is missing:

Get tokens for the user

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/tokens/forUsers' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<user-id>]
  }'

Get tokens for the document

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/tokens/forDocs' \
  --header 'Content-Type: application/json' \
  --data '["<document-id>"]'

Entitlement is NONE when there is no overlap between the two token sets. If either returns an empty list, the issue is with the underlying provider.

For Expert Calls documents specifically, query the provider directly

Get user entitlements from expert-calls-api

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/entitlements/user-entitlement-properties' \
  --header 'accept: */*' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<user-id>]
  }'

Get document entitlements from expert-calls-api

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/entitlements/document-entitlement-properties' \
  --header 'accept: */*' \
  --header 'Content-Type: application/json' \
  --data '{
    "documentIds": ["<comma separated document-id list >"]
  }'

If the provider is consistently returning empty or incorrect tokens, this is a provider team issue — escalate to the appropriate team.

2. User Cannot See Expert Insight or Broker Research Documents

Triage

Users in a private cloud environment cannot access expert calls. Private cloud environments route requests for expert calls content to the mothership via an umbrella user that represents the entire private cloud instance. If this umbrella user is missing entitlement permissions or is misconfigured, all users in that private cloud environment will be blocked from accessing those expert calls.

Troubleshooting

Identify the umbrella user for the private cloud environment.

First, get the company id:

# Port forward to user-service.platform svc
curl -X 'GET' \
  'http://localhost:<port from port-forward>/internal/v2/companies?page=0&pageSize=10&q=<partial company name>' \
  -H 'accept: application/json'

Second, use the company id in the next api call:

# Port forward to user-service.platform svc
curl --location 'http://localhost:<port from port-forward>/internal/user/with-flags?page=0&pageSize=20' \
  --header 'Content-Type: application/json' \
  --data '{
    "features": ["PRIVATE_CLOUD_ENTITLEMENTS_USER"],
    "companyId": "<Company Id>"
  }'

Contact Alphasense Support.

To be investigated on Saas enviroment by Alphasense Support

Verify the umbrella user can open the affected document type in production:

curl --location 'entitlement-ng-realtime.applications.svc.research.local/v1/entitlement' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "id": <umbrella-user-id>
    },
    "documents": [
      {
        "id": "<document-id>"
      }
    ]
  }'

If documents are not AVAILABLE for the umbrella user, check the provider tokens directly (see first scenario above).

Check what permissions the umbrella user currently has:

curl --location 'http://user-service.platform.svc.research.local/internal/user/<umbrella-user-id>/features'

For expert calls access, confirm the following permissions are present:

• "EXPERT_CALLS": "GLOB",
• "TEGUS_TRANSCRIPTS": "GLOB"

3. Stale Entitlement Cache After License Change (Private Cloud)

Triage

When licenses are modified for an umbrella user of a private cloud, the cache must be manually cleared for users affected on PC side, to force a fresh token fetch on the next request and not return the stale tokens.

Troubleshooting

Identify the local user IDs of the affected users within the private cloud environment, then issue the following cache clear request.

NOTE: Use the local PC user ID, not the umbrella user ID. The cache is keyed per local user in the PC environment.

Clear the entitlement token cache for a user

Via port-forward:

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/tokens/forUsers/clearTokensInCache' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<local-pc-user-id>],
    "providers": ["PUBLIC_DOCS"]
  }'

Via internal DNS (PC environment):

curl --location 'http://entitlement-ng-realtime.applications.svc.research.local/v1/tokens/forUsers/clearTokensInCache' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<local-pc-user-id>],
    "providers": ["PUBLIC_DOCS"]
  }'

NOTE: The providers field accepts the following values: PUBLIC_DOCS, BROKER_RESEARCH, USER_DOCS for PC env.

4. Latency Breach on Token Fetch Endpoint (Timeout)

Triage

The /v1/tokens/forUsers endpoint is timing out or exceeding acceptable latency thresholds. This results in delayed or failed entitlement checks, which can surface as slow document loading or incomplete search results across the platform.

Troubleshooting

Check token fetch for a user across all providers:

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/tokens/forUsers' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<user-id>],
    "providers": []
  }'

Narrow the check to a specific provider or set of providers to isolate the slow hop:

# Port forward to entitlement-ng-realtime.applications svc
curl --location 'http://localhost:<port from port-forward>/v1/tokens/forUsers' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": [<user-id>],
    "providers": ["FACTSET_RESEARCH", "REFINITIV_RESEARCH"]
  }'

Check entitlement-ng-processing logs to confirm whether elevated errors are present and identify the slow provider.