Subscription & Roles

This guide explains how subscriptions work in Knowledge Discovery and how to manage discovery roles for access control.

Prerequisites

Before managing subscriptions and roles, ensure you have:

• Active Hyland Experience Account - Valid Account with Environment access
• Administrative Access - Account admin or subscription manager role
• Active Subscription - Knowledge Discovery App Subscription in your Environment
• Authentication - Valid access token with appropriate scopes

See Getting Started for initial setup and Authentication for obtaining access tokens.

Overview

Knowledge Discovery uses a subscription-based model where an Account subscribes to the Discovery App within an Environment. Users and groups are assigned specific roles to control access to features and data.

Key Concepts

• Account - Top-level container for your organization's Hyland Experience resources
• Environment - Isolated workspace within an Account that contains Subscriptions and their data
• Subscription - Your license to use the Knowledge Discovery App within an Environment
• App - The Knowledge Discovery application and its associated services

Subscriptions

What is a Subscription?

A Subscription is your Account's license to use the Knowledge Discovery App. It defines:

• Environment Association - Links the App to a specific Environment within your Account
• Resource Allocation - Determines quotas and limits for the App
• Usage Tracking - Monitors usage for billing purposes
• Feature Access - Controls which App features are available
• Timeframe - Defines when the Subscription is active

Managing Subscriptions

Administrative Access Required

Subscription management requires administrative privileges in your Hyland Experience Account.

Subscriptions are created through Hyland's sales process (Salesforce) and managed through the Hyland Experience Cloud admin portal. Contact your Hyland representative for subscription management assistance.

Environment Isolation

Each Environment within your Account provides isolated data and configuration:

• Separate Data - Environments maintain separate agents, questions, and usage data
• Independent Configuration - Each Environment can be configured independently
• User Access Control - Environments can be configured to allow access by specific users
• Multiple Environments - Accounts can contain multiple Environments (e.g., dev, staging, production)

Example Structure:

Account (Your Organization)
├── Environment (Development)
│   └── Subscription (Knowledge Discovery)
│       └── Agents, Questions, Data
├── Environment (Staging)
│   └── Subscription (Knowledge Discovery)
│       └── Agents, Questions, Data
└── Environment (Production)
    └── Subscription (Knowledge Discovery)
        └── Agents, Questions, Data

Discovery Roles

Role-Based Access Control

Knowledge Discovery implements RBAC (Role-Based Access Control) to manage user permissions. Roles are assigned at the user or group level.

Available Roles

Discovery User

Permissions:

• View agents assigned to their user or group
• Submit questions to authorized agents
• View answers to their questions
• Send feedback on answers
• View question history

Typical Users: End users, employees, customers

Discovery Manager

Permissions:

• All Discovery User permissions
• View all agents
• Create new agents
• Update existing agents
• Delete agents
• Configure agent access rights
• Check feedback breakdown

Typical Users: Knowledge managers, content administrators

Role Assignment

Roles are assigned through the Hyland Experience Identity platform. Here's how role assignment works:

Agent Access Rights

In addition to roles, agents have their own access control mechanism through Access Rights:

{
  "accessRights": [
    {
      "type": "User",
      "id": "user-guid-here"
    },
    {
      "type": "Group",
      "id": "group-guid-here"
    }
  ]
}

Access Rights Logic:

• Users can only interact with agents where they're explicitly granted access via User or Group
• Group membership is evaluated from the identity provider
• Access rights are evaluated in addition to role permissions

Permission Matrix

Action	Discovery User	Discovery Manager
List agents	✓ (with access only)	✓ (all agents)
View agent details	✓ (with access only)	✓ (all agents)
Create agent	✗	✓
Update agent	✗	✓
Delete agent	✗	✓
Submit question	✓	✓
View answers	✓ (own questions)	✓ (own questions)
Send feedback	✓	✓
View question history	✓	✓
Check feedback breakdown	✗	✓

Access Control Examples

Example 1: Department-Specific Agent

Create an agent accessible only to the HR department:

{
  "name": "HR Policy Agent",
  "description": "Agent for HR policies and procedures",
  "modelName": "bedrock-amazon-nova-micro",
  "accessRights": [
    {
      "type": "Group",
      "id": "hr-department-group-id"
    }
  ],
  "sourceIds": ["hr-documents-source-id"]
}

Result: Only users in the HR department group can:

• See this agent in their agent list
• Submit questions to this agent
• Receive answers from this agent

Example 2: Executive Access

Create an agent accessible to specific executives and all members of the executive group:

{
  "name": "Executive Intelligence Agent",
  "description": "Strategic insights for executives",
  "modelName": "bedrock-amazon-nova-micro",
  "accessRights": [
    {
      "type": "Group",
      "id": "executives-group-id"
    },
    {
      "type": "User",
      "id": "ceo-user-id"
    },
    {
      "type": "User",
      "id": "cfo-user-id"
    }
  ],
  "sourceIds": ["executive-reports-source-id", "financial-data-source-id"]
}

Example 3: Public Knowledge Agent

Create an agent accessible to all authenticated users (assuming all users are in a company-wide group):

{
  "name": "Company Handbook Agent",
  "description": "General company information",
  "modelName": "bedrock-amazon-nova-micro",
  "accessRights": [
    {
      "type": "Group",
      "id": "all-employees-group-id"
    }
  ],
  "sourceIds": ["company-handbook-source-id"]
}

Checking User Permissions

Via Agent List API

Users can list agents to see which ones they have access to:

curl

# Lists only agents the user has access to
curl -X GET "${DISCOVERY_API_BASE_URL}/agent/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Handling Permission Errors

When a user attempts to access a resource they don't have permission for:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "User does not have permission to access this agent"
}

Best Practice: Filter UI to show only agents the user has access to, rather than showing all agents and handling 403 errors.

Best Practices

1. Use Groups for Scalability

Assign access rights to groups rather than individual users:

✅ Good:

{
  "accessRights": [
    {"type": "Group", "id": "sales-team-group"}
  ]
}

❌ Avoid:

{
  "accessRights": [
    {"type": "User", "id": "user1"},
    {"type": "User", "id": "user2"},
    {"type": "User", "id": "user3"}
    // ... managing many individual users
  ]
}

2. Principle of Least Privilege

Grant users the minimum permissions needed for their role.

3. Regular Access Reviews

Periodically review agent access rights and user roles to ensure they remain appropriate.

Troubleshooting

User Can't See Any Agents

Possible Causes:

1. User doesn't have Discovery User role
2. No agents have access rights including the user or their groups
3. Subscription is not active

Resolution:

1. Verify user has appropriate role assigned
2. Check agent access rights configuration
3. Verify subscription status

User Can't Create Agents

Possible Causes:

1. User has Discovery User role instead of Discovery Manager
2. User doesn't have write permissions

Resolution:

1. Assign Discovery Manager role
2. Verify Subscription includes write permissions

Access Denied Despite Group Membership

Possible Causes:

1. Group ID mismatch between IdP and agent configuration
2. Group sync delay
3. User not yet added to group in IdP

Resolution:

1. Verify group ID in agent access rights matches IdP
2. Wait for group membership synchronization (typically real-time)
3. Confirm user membership in IdP