Usage and Permissions

In Serenity* AI Hub, there are two main ways to control access and permissions for agents: API Keys and Users. Below is a simple overview of how each works, how to configure them, and the main usage flows.

API Key Permissions

API Keys grant access to agents via the Serenity* AI Hub API. Each key is assigned a specific permission for each agent, defining what actions are allowed. API Keys can be scoped to individual agents or, in some cases, have global access across all agents.

How to Add or Assign an API Key

1. Go to the agent's permissions section.
2. Click Assign Key.
3. A side panel will open. You can select an existing key you own (only keys you created are shown), or create a new key directly from the side panel.
4. If creating a new key, enter a name and select the permission for this agent:
   • Agent Administrator: Full access
   • Agent Auditor: View logs/audit and execute the agent
   • Agent Execution: Execute only
5. Click on "Confirm" to assign the new API key to the agent.
6. Once assigned, the key appears in the agent's key list.
   • If you are the owner, you can edit its permission or unassign it.
   • If you are not the owner, you can only unassign it from the agent.

API Key Scopes

API Keys in Serenity* AI Hub have two possible scopes, which define their reach and how they are managed:

Agent Scope:

• Created directly from an agent's permissions section.
• Always linked to one or more specific agents.
• Permissions (Administrator, Auditor, Execution) are set per agent.
• Can only be used to access the agents to which they are assigned.
• Only the owner can edit a key's permissions or assign it to agents.
• The same key can be assigned to multiple agents, with different permissions per agent.
• Unassigning a key removes its link to the agent, but does not delete the key.

Global Scope:

• Created from DevTools, not from an agent.
• Not linked to any specific agent; these keys apply to all agents within the tenant or subtenant.
• Permissions are determined by the assigned role for each key.
• Examples of global API Keys include:
  • main: Has full administration, audit, and execution permissions for all agents.
  • agent-execution: Has execution permission for all agents, but cannot administer or audit.

Note: The main and agent-execution keys are generated automatically by the system and cannot be edited or deleted.

User Permissions

User-based permissions allow you to control which users can manage, audit, or execute an agent. By default, users with certain roles (such as Agent-Administrator, Agent-InstanceUser, Agent-Execution, etc.) have access to all agents. Defining user permissions on an agent allows you to restrict access, so that only explicitly assigned users can operate or manage that agent.

This means:

• Adding users to an agent's permissions restricts access to only those users, overriding the default open access for users with general roles.
• User permissions are a way to lock down sensitive or critical agents to a specific set of people.
• In contrast, API Keys expand access to agents, allowing external systems or users to interact with them in a controlled manner.

How to Add or Assign a User

1. Go to the agent's permissions section.

2. To enable user-based restrictions, you can activate them selectively by operation type:

   • Administrator: Toggle to restrict who can manage agent settings and configurations
   • Auditor: Toggle to restrict who can view logs and audit information
   • Executor: Toggle to restrict who can run the agent

   

3. Restrictions have dependencies and work with cascade behavior: you cannot restrict execution without auditing, or auditing without administration. The system automatically enables/disables restrictions to maintain this hierarchy. Additionally, when you enable any restriction, the current user is automatically assigned as Administrator.

   

4. To add more users, each restriction type has its own Add User button:

   • Add Administrator: Adds users who can manage agent settings and configurations
   • Add Auditor: Adds users who can view logs and audit information (and execute the agent)
   • Add Executor: Adds users who can run the agent
   • A side panel opens where you select a user from the dropdown (only users from the same subtenant are listed).

5. The user appears in the list with their assigned permission.

User Permission Rules

• Each operation type (administration, auditing, execution) can be restricted independently.
• When a restriction is active for an operation, only users with explicit permission for that operation can perform it.
• When no restriction is active for an operation type, users with general roles continue to operate as before.
• There must always be at least one administrator if any restriction is enabled.
• Special roles (TenantAdministrator, SubtenantAdministrator) can always view and edit all agents regardless of user-based restrictions.
• If an agent has assigned users, only those users can operate it according to their permission.
• The permission assigned to a user for an agent takes precedence over their general role.
• You can remove all users if needed, but at least one admin is required if any users are present.
• Agent restrictions for users only apply when using the API with user authentication (username/password) or when navigating within Serenity* AI Hub platform.
• When using the API with an API Key, only the permissions or roles of the API Key are considered, not the user-based restrictions.

Best Practices

• Regularly review assigned keys and users.
• Use the minimum necessary permission level.
• Remove access that is no longer needed.