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.
   • If creating a new key, enter a name and select the permission for this agent:
     • Agent Administrator: full access
     • Agent Execution: execute only
     • Agent Auditor: view logs/audit and execute the agent
   • Assign the key to the agent.
4. 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.

• 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.

Key Usage Notes

• The same key can be assigned to multiple agents, with different permissions per agent.
• Only the owner can edit a key's permissions or assign it to agents.
• Unassigning a key removes its link to the agent, but does not delete the key.

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, toggle the Restrict access to this agent switch.
   • When you enable this switch, the current user is automatically assigned as Administrator, since every restricted agent must always have at least one administrator.
3. To add more users, click Add User:
   • A side panel opens:
     • Select a user from the dropdown (only users from the same subtenant are listed).
     • Assign a permission:
       • Administrator: full access and editing
       • Auditor: view logs and details, and execute the agent
       • Executor: execute only
4. The user appears in the list with their assigned permission.

User Permission Rules

• There must always be at least one administrator if 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 the platform UI.
• 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.