Role Management

https://app.example.com is an example address. Replace it with the actual address of your environment, retaining the route path and query parameters.

1. Configuration Goal

Use a Role to place a group of users within the same authorization scope and configure the models they are allowed to use (Allowed Models). Role configuration affects the models users can select and call in AOS Work. Explore Management also uses Roles to determine resource visibility.

This chapter describes Role configuration and its effect on user model access and Explore resource visibility.

2. Configuration Entry

Role management: Account → Roles

Related pages covered in this chapter:

• Accounts: Bind users to one or more Roles;
• Models: Configure models that can be authorized for a Role;
• Explore Management: Configure Explore visibility for Skills, Works, and Connectors by Role.

3. Role Configuration Scope in the Current Version

3.1 Role List

After opening Account → Roles, you can view and search the Role list and use New to create a Role. The current list displays:

• Role name;
• Description;
• Created;
• Updated.

Role names, example Roles, the Default label, and counts in the list are data from the current environment. Do not treat them as default configuration or initialization requirements for other environments.

3.2 Create or Edit a Role

When creating or editing a Role, the current version uses the following configuration fields:

Allowed models should include only models that meet the availability conditions on the Models page. A Role stores the stable identifiers of models; it does not copy model credentials, Endpoint, display information, or Credits conversion configuration.

4. Pre-configuration Checklist

Before starting, confirm:

1. The target Role's business purpose, name, and description are confirmed;
2. Users who need this Role already exist, or can later be assigned the Role from Accounts;
3. The models to authorize have been configured on the Models page;
4. The Model Group and Model are enabled, the most recent model test succeeded, and the model display name and logo are valid;
5. If the Role needs to discover Explore resources, the Skills, Works, or Connectors that should be visible to it are specified.

Enter sensitive credentials such as API Key and Access Token only in Models or the relevant connection configuration page. Do not write them in the Role name, description, ordinary records, or ordinary documents.

5. Create a Role

1. Open Account → Roles.
2. Click New.
3. Enter the Role name in Role name.
4. Enter the Role's purpose and scope in Description.
5. Select the models to authorize in Allowed models.
6. Click Create role to save.

If the Role should not currently grant any models, leave Allowed models empty. Saving it does not give users with that Role access to all models.

6. Edit a Role

1. Search for and locate the target Role in the Role list.
2. Open the Role's action menu and enter edit mode.
3. Modify Role name, Description, or Allowed models.
4. Save the changes.

After Allowed models is changed, the new authorization scope applies to subsequent model selection and calls. Actual model information already recorded in historical messages is not rewritten by a Role change.

7. Role Relationships with Other Modules

7.1 Accounts: Role Assignment

A Role is only an authorization set. A user must be bound to the Role through Accounts before receiving that Role's model scope. When a user is bound to multiple Roles, take the union of their Allowed models.

For account creation and role assignment, see Account Creation. For credit allocation, see Credits Plan.

7.2 Models: Source of Allowed Models Candidates

Roles do not create models or store model connections. Only models that meet all of the following conditions should appear as Allowed models candidates:

• The Model Group is enabled;
• The Model is enabled;
• The most recent model test (Test Model) succeeded;
• Model Display Name and Model Logo are valid.

If a Model Group or Model is disabled, its test becomes invalid, or its display configuration becomes invalid on the Models page, a Role reference cannot bypass these availability restrictions.

7.3 AOS Work: User Model Selection and Calls

The user's final selectable model scope is:

Union of the current user's Roles' Allowed models ∩ currently available models in Models

Therefore:

• A user with one Role uses that Role's valid model scope;
• A user with multiple Roles uses the union of the Roles' authorized scopes;
• Newly added models are not automatically added to existing Roles; an administrator must explicitly authorize them;
• Subsequent new calls are affected immediately after Role authorization is removed or a model becomes unavailable;
• If the model currently selected by a user is no longer in the valid scope, the system must not silently replace it. The user must select a valid model again before sending the next message.

Roles do not configure a default model, fallback model, or model priority.

7.4 Explore Management: Resource Visibility

In a specific Explore Release in Explore Management, you can configure Visible Roles:

• Select one or more Roles allowed to view the resource;
• Multiple Roles use OR matching: a user can see the resource if they have any selected Role;
• If no Role is selected, the resource is visible to all Roles;
• Visibility is recalculated from the user's current Roles;
• This configuration applies only to published Skills, Works, and Connectors.

Visible Roles is a resource-side setting and does not write back to or change a Role's Allowed models. Library and Base reuse the existing App distribution configuration and are not included in the Role visibility configuration for new Explore Releases in this version.

8. Post-save Verification

After saving the Role, verify in the following order:

1. Return to the Role list and confirm that Role name, Description, and Updated reflect the change;
2. Open Accounts and confirm that the target users are bound to the Role;
3. Open Models and confirm that authorized models still meet the enabled, test-success, and valid-display-configuration conditions;
4. Using a user bound to the Role, enter AOS Work and open the model selector to confirm that only authorized and currently available models are shown;
5. If Explore resource discovery must be controlled, open Visible Roles for the resource in Explore Management and confirm that the Role selection matches expectations;
6. Send a minimal test message and confirm that the server accepts the selected model call and records usage under the existing Credits rules.

9. Completion Criteria

• The Role name and description are filled in and saved successfully;
• Allowed models is explicitly configured for the business need or intentionally left empty;
• Target users are bound to the Role in Accounts;
• The user-side model selector shows only models authorized for the Role and currently available;
• New calls after a Role change or model unavailability follow the re-selection rule;
• When Explore resources must be restricted, the relevant Explore Release has Visible Roles configured;
• No sensitive credentials are recorded in the Role configuration or documentation.