Managing Roles

Roles determine what users can or cannot do in the Platform.

The ability to configure roles provides the following advantages:

• Greater control over governance: Organizations can define precise access permissions aligned with policies.

• Separation of duties: Ensures compliance by granting the minimum required permissions to each role.

• Scalable and consistent governance: Custom roles, classified by Role Type, make each user's operational scope explicit. This enables different governance models for internal teams, partners, and citizen developers, while simplifying access management.

The Platform comes with a set of default roles (Owner, Organization Admin, Group Admin, Contributor, Consumer, Guest and Visitor), marked as Default in the list of roles. Default roles are read-only: they can be viewed but not modified or deleted. Administrators can create custom roles, from scratch or by cloning an existing role.

Roles also have a Role Type. Available types are:

• Tenant Admin: for users with full visibility and control across the tenant. Users with this role have cross-tenant visibility over other Organizations, however they are not equivalent to tenant "owners", as they cannot fully access the Administration section. They may still create new organizations and be involved in the end-to-end onboarding of new users and Organizations.

• Group Member: for users operating within a specific organization or group.

• Guest Role Type: is system-managed and includes the default Guest and Visitor roles, which are not customizable. These are reserved for users who access the Platform without login (Visitors) or who do log in but do not belong to any Organization.

NOTE: Users can have multiple roles if they belong to multiple organizations, since they can have a different role for each organization.

NOTE2: The Role Type is chosen when the role is created and cannot be changed afterwards.

Permissions

The permissions of a role are organized in two tabs, each showing how many permissions are selected out of the total:

• Environment Permissions: what the role can do in each environment (for example DEV, TEST and PROD): Publication, Republication and Subscription.

• Entities Permissions: what the role can do on each entity, in each of its statuses. The entities are: Apps, Widgets, Organizations, Received Subscriptions, Requested Subscriptions, Digital Products, APIs, IP Addresses, Assets, Key Sets and Groups. For example, for APIs you decide who can propose a concept, request validation, publish, promote, deprecate or retire; for Groups, who can add or remove users and change their roles.

Creating a role

IMPACT: when a role is newly created, the notifications for that role should also be reviewed and edited accordingly (see chapter Notifications).

Steps:

1. Navigate to Administration > Access Management > Roles.

2. Click Add to create a new role, or select an existing role and click Clone to start from a copy of its permissions.

3. Complete the following fields:

   • Name (required);

   • Description (required);

   • Role Type (required).

4. Choose the Permissions:

   • in the Environment Permissions tab, select the actions allowed in each environment;

   • in the Entities Permissions tab, expand each entity and select the actions allowed in each status. Use the search to find a permission, and Select all / Expand all to work faster.

5. Click Save.

Editing a role

Steps:

1. Navigate to Administration > Access Management > Roles.

2. Select a role from the list.

3. Update the details and the permissions.

4. Click Save (or Reset to discard the unsaved changes).

NOTE: Changes apply immediately to all the users who have the role.

Deleting a role

Steps:

1. Navigate to Administration > Access Management > Roles.

2. Select a custom role from the list.

3. Click Delete and confirm.

NOTE: Default roles cannot be deleted.

Assigning roles to users

Steps:

1. Navigate to Organizations.

2. Select the Organization and Group where a User is positioned.

3. Click the Role dropdown next to the user's name.

4. Select the new role.

Managing Organizations

Organizations are the largest subdivision of users in the Platform. They can be used arbitrarily depending on the adopted operating model, but they are generally used to represent business or development units, providing scopes of action to sets of users.

Organizations can have different Types, which determine the largest strict classification of users in the Platform. Organization Types are:

• Internal: For units of users belonging to the core enterprise, such as developers, business, analysts, devops, etc. With the appropriate permissions they govern all entities in the Platform.

• Partner: For units of users who are partners of the core enterprise, and who are expected to have limited access to the entities of the Platform, mainly to consume digital products and consult the catalogs.

• Citizen: Same as Partners, but used when a higher granularity is required, particularly when the Organization is expected to represent a single user.

Users who do not belong to an organization are considered Guests.

NOTE: Users who are in an Organization of one Type cannot belong to Organizations of another Type. (They can however belong to multiple Organizations of the same Type.)

In the Organizations section, organizations are listed in one tab for each Organization Type, with their name, contact, categories and external ID.

Searching for an organization

The search results will display relevant organizations based on the selected searching criteria.

Steps:

1. In the Organizations section, use the search bar.

2. Search by Name, or use the filters:

   • By Organization Category: lists organizations with a specific category.

   • By Group: lists organizations containing a specific group.

   • By User: lists organizations associated with a specific user.

Creating an organization

NOTE: If your installation is integrated with an API gateway that manages organizations, creating or editing organizations will generate or update them on the API gateway. In that case you will see a Synchronize button in the organizations list. Synchronization errors are notified to the administrators (see chapter Notifications).

IMPACT: Organizations without a category see only the digital products shared explicitly with them. Categories can be used to extend visibility and automatic subscription approvals to whole groups of organizations: changing the categories of an organization may change what its users see in the catalogs (see chapters Default entity visibility and Security governance).

Steps:

1. Navigate to the Organizations section in the main menu (or use Quick actions > New Organization).

2. Click Add to create a new organization.

3. Enter the required details:

   • Name (required): unique identifier for the organization.

   • Organization Contact (required): default email for organization-related communications.

   • Description (required): a brief summary of the organization's purpose.

   • External ID (optional).

   • Categories (optional).

4. Once all mandatory fields are completed, the Save button becomes active. Click it to confirm creation.

NOTE: Every new organization has the default Org Admins group.

Editing an organization

Steps:

1. In the Organizations section, open the organization to edit.

2. Click Edit.

3. Modify the necessary details (name, contact, description, external ID, categories).

4. Click Save to confirm the changes.

Deleting an organization

To proceed to delete the organization no digital products or applications should be associated with the organization; if there are any, please ensure that all associated entities (digital products and applications) are reassigned before proceeding.

NOTE: If your installation is integrated with an API gateway that manages organizations, deleting organizations will delete them on the API gateway too.

Steps:

1. Navigate to the Organizations section.

2. Click Delete next to the target organization.

3. Confirm the action in the pop-up window.

Managing Groups

Groups are a subdivision of Organizations, and are generally managed by Group Admins and Organization Admins.

The difference between the two administrative roles is the following:

• the Organization Admin (users belonging to the Org Admins group of an organization) manages the organization and all its groups: edits the organization, creates groups, adds and removes users, changes their roles;

• the Group Admin manages only the members and the data of their own group: adds users, edits the group, changes the roles of the members and removes them.

NOTE: Users may belong to only one Group within each Organization.

NOTE2: The Org Admins Group is a default Group of any Organization and cannot be changed (but it can be hidden: see chapter Stakeholder profiling and features, area Organizations). Users belonging to that group will have only the default Organization Admin role. If you want to customize that role you'll need to create a dedicated Group and Role, and move the user into that Group, ignoring the Org Admins Group.

NOTE3: All the members of a group share the same digital products, applications, subscription requests and credentials.

Creating a group

Steps:

1. Navigate to the Organizations section.

2. Select the organization where the group will be created.

3. Click New group and enter the required details:

   • Name: unique identifier for the group.

   • Group Contact: default email for group communications.

   • Description: brief explanation of the group's purpose.

4. Click Save to finalize creation.

Editing a group

Steps:

1. In the Organizations section, open the organization and locate the group to be edited.

2. Click Edit group.

3. Modify the necessary details (name, contact, description).

4. Click Save to save changes.

Deleting a group

To proceed deleting the group it must not contain any digital products or applications. Remember, the Org Admins Group cannot be deleted unless the entire organization is deleted.

Steps:

1. Navigate to the Organizations section.

2. Select the organization containing the group.

3. Click Remove group next to the group and confirm the action.

NOTE: Once deleted, the group can no longer contribute to the ecosystem.

Viewing users in a group

Clicking on a user provides a detailed overview of their roles and permissions.

Steps:

1. Navigate to the Organizations section.

2. Select the organization and group.

3. Browse the user list or search for a specific user.

Adding a user to a group

To add a User in a group it must be registered on the Platform or has to be invited to join the Platform.

Steps:

1. Navigate to the Organizations section.

2. Select the organization and group.

3. Click Add user and choose one of the following:

   • search and select an existing user;

   • enter an email to invite a new user.

4. Assign a role and confirm the addition.

Removing a user from a group

Remember that any digital products or applications they owned must be reassigned after the user is removed from the group.

Steps:

1. Navigate to the Organizations section.

2. Select the organization and group.

3. Locate the user and click Remove.

4. Confirm the action.

Managing Users

The Users tab of the Organizations section lists all the users registered on the Platform, with their username, name, surname, email and the organizations they belong to. It is available to the Owner and to users with a Tenant Admin role.

Steps:

1. Navigate to Organizations > Users.

2. Search for a user by name or email.

3. Open the user to see their information and the organizations and groups they belong to.

NOTE: If your installation uses a corporate identity provider (single sign-on), internal users can be onboarded automatically at their first login, and their email is kept aligned with the identity provider. Federated users cannot change their email from the Platform.

HINT: If several federated users share the same email address (for example technical accounts), you can show their External ID next to the email to tell them apart (see chapter Stakeholder profiling and features, area Account).

Managing Join Requests

Join Requests are requests of users to join organizations they do not yet belong to. Users send them from Quick actions > Join an organization, choosing one or more organizations.

NOTE: The possibility can be disabled for users of different Types (Internal, External, Guests) so that only Owners and Org Admins can choose where to place users. This is particularly important if you want to avoid revealing your Organizations to Guest Users (see chapter Stakeholder profiling and features, area Join Requests).

Steps:

1. Go to Join Requests > Received in the Organizations section.

2. Locate the request (use Inspect request to see its details) and choose one of the following:

   • Approve: assign the user a group and role, then confirm. The user gains access to the organization based on the assigned group and role.

   • Reject: deny the request, and it will be marked as rejected.

NOTE: The Sent tab lists the join requests sent by the user themselves, with their status (Pending, Approved, Rejected).

Managing Invitations

When a user is invited to join an Organization, if they are not already registered on the Platform, an Invitation is created. Invitations allow Owners, Org Admins and Group Admins to handle the onboarding of new users on the Platform.

When an invited user registers, the invitation becomes Accepted. An invitation may also be withdrawn or expire (see chapter System, Invitation Expiration). Invitations can also be resent if they are approaching their expiration, triggering a notification to the user's email.

The invitations list shows, for each invitation, the email, organization, group, role, creation date, status, days to expiration and last update.

Steps:

1. Go to Invitations in the Organizations section.

2. Locate the invitation using the search function.

3. You may choose to inspect, resend or withdraw the invitation.

NOTE: The invitations feature can be enabled or disabled for each stakeholder type (see chapter Stakeholder profiling and features, area Invitations).