> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/6/admin-essentials/authorization/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Configure authorization > How to manage users, groups, roles, and service accounts through the Authorization interface in Admin Essentials. **Authorization** is the main interface in Admin Essentials for administering and viewing users, groups, and roles. Your permissions determine which views, features, and interactions are available in the UI. There are two ways to access **Authorization**: from the Itential Platform home page, navigate to **Admin Essentials** → **Quick Start** → **Authorization**; or click **Authorization** in the left sidebar to open the accordion menu. ![](/_fern-img/43933c80f8803eb035a8e19f2389a43c8764ddf780ac53cdd995290f206b6044.webp) If you have Cisco NSO and want to use the NSO External Authentication script, you need network connectivity between the two (typically port 3000). For more information, see the [NSO Network Adapter Integration guide](/adapters/configure/reference/nso#nso-external-authentication-configuration). ## Terminology | Term | Definition | | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User | An entity that can perform specific actions within multiple Itential Platform applications based on group associations. | | Group | A collection of roles that can be assigned to a user. | | Role | A collection of granular-level privileges that can be assigned to groups. | | Permission | Authorization granted to an API and a specific page view. | | Provenance | Refers to the source (origin) of a group. For external groups, this is set to the Itential Platform AAA `adapterId`. For Itential Platform groups, it is not set. | ## Users A user is an entity that comes from an external AAA system such as LDAP. All operations within Itential Platform are associated with a user. Itential Platform lets you assign roles directly to users, and administrators can manage user membership through groups. Users may be members of any number of groups and, through group membership, may be assigned any number of roles. User roles, whether directly assigned or inherited from a group, determine what the user can see and do within Itential Platform. The final permission set of a user is a combination of permissions granted to all roles assigned to the user and to any groups of which the user is a member. ### View and filter users Because users are accounts from an external system, Itential Platform creates a user record when someone has successfully logged in using their AAA system credentials. To view the **Authorization → Users** table, you must have permission for the `authorization.getAccounts` method. This allows you to access the page, view the list of users, and see their login status. The indicator circles under the **Active** column header denote the login status of each user: * Blue: User is currently logged in. * Red: User is deactivated. * Grey: User is not logged in. Active Login Session Management became available in release 2023.2 and later. Earlier releases don't support viewing active login sessions. Filter the **Users** table by login status using the popover menu in the top-right. Click the vertical ellipsis (⋮) to display two filter toggles: **Show Active Users Only** and **Show Deactivated Users**. ![](/_fern-img/85c22adfe7b0d7679184ac7353ff985f1b694c416dc8bba4cba5d0d5c84fce26.webp) ### Configure role assignments for users There are two ways to assign users to **Roles**: directly, or by group membership. To assign **Roles** directly to a user: #### Locate the user Locate the user you want to assign. You can filter the user list by typing in the `username` column header search box. #### Update role assignments Add or remove role assignments using the checkbox. You can filter the roles list by typing in the **Search** field. #### Close Click **Close** when done. Roles assigned by groups are grayed out (disabled), indicating the assignment is inherited. ![](/_fern-img/388a146714a952c4df59a109446d839e71fdb57b953c46488ac4d6697108b3b5.webp) ### Configure group membership for users The external AAA system manages external group memberships; they can't be edited in Itential Platform. You can only add or remove users from Itential Platform groups within Authorization. To change the **Groups** to which a user belongs: #### Open the Groups tab Click the **Groups** tab option. #### Find the group Find the group in the list. You can filter the list by typing in the column header textbox. #### Update membership Add or remove group membership using the checkbox. #### Close Click **Close** when done. ![](/_fern-img/17b72316bf3b6a2f599b4307c35141e6cd4d5cd1b487aedb0a1cd17882fa405d.webp) AAA-managed group memberships will be grayed out (disabled), indicating the membership is not editable in Itential Platform. ### Forced Logout Administrators can force users to log out from the Authorization interface. Administrators must have permission for the `Authorization.forceLogout` method. Select users using the checkboxes, then click **Log Out** at the top. ![](/_fern-img/ad59a31f66e95ca742d41624e5bbc074e89c05c1d0454a102d79c827e5fb5cd6.webp) ## Groups An Itential Platform **Group** is an account created within Itential Platform. Users are assigned to Itential Platform groups through **Authorization**, but are assigned to external groups through the external AAA system. An external group comes from an external AAA system such as LDAP and can't be created within Itential Platform. If `User1` is a member of `Group1` and starts a job, and `User2` is not a member of `Group1`, then `User2` will not be able to see the job. ### Assign roles to groups External groups can't be created within Itential Platform. Itential Platform creates the external group record after learning it from the AAA system. Roles are assigned to groups in two ways: directly, or by membership in another group. To directly assign roles to a group in Itential Platform: #### Navigate to Groups Select **Authorization** → **Groups** from the navbar on the left. A list of defined groups displays. #### Locate the group Locate the group you want to assign to a role. You can filter the list by typing in the **Name** column header search box. #### Open the View Group dialog Click the eye icon at the end of the table row to open the **View Group** dialog. The **Roles** tab displays by default. #### Locate the role In the **Edit Group** modal, locate the role you want to assign. Filter the list by typing in the **Name** or **Source** search bar. #### Update assignment Add or remove a role assignment by selecting the checkbox. #### Close Click **Close** when done. Roles assigned by other groups are grayed out (disabled), indicating the assignment is inherited. ![](/_fern-img/ecb94ebb96f598ee3daf6942963c02dfb31b1c6ed747b5b6579c242f12e5e34b.webp) ### Assign group membership Itential Platform groups and external groups can be given membership to an Itential Platform group; however, neither can be given membership to an external group. #### Navigate to Groups Select **Authorization** → **Groups** from the navbar on the left. #### Select a group Locate the group in the list and click the eye icon to open it. #### Open the Groups tab From the **Edit Group** modal, select the **Groups** tab. #### Update membership Add or remove group membership by selecting the checkbox. #### Close Click **Close** when done. ### Identify group members #### Open the Members tab Select the **Members** tab in the **Edit Group** modal to see the users who are direct members of the group. Inherited memberships aren't indicated. #### Find a member Locate the member username in the list. You can filter the list by typing in the **Search** bar. #### Close Click **Close** when done. ## Roles A role is a set of permissions assigned to users and groups that grants access to one or more endpoints. Roles are predefined in the `pronghorn.json` file for each application and assigned to methods and views with the `roles` property. ### Built-in Platform roles The following built-in roles come with Itential Platform with ready-to-use permissions and access levels that define what actions users can perform. These built-in roles can serve as a starting point for custom roles with more precise control. Itential Platform supports custom roles tailored to your organization's security and business needs. | Role | Description | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | admin | Full permission to Itential Platform to configure and manage access control. | | apiread | Provides view-only access to API information, but does not allow you to make changes. | | apiwrite | Provides access to view API information and make changes. | | authorization | Provides access to modify RBAC and control authorization of data. | | designer | Grants access to build workflows and automations within Itential Platform's Lifecycle Manager, Studio, and Operations Manager. | | engineering | Grants access to perform engineering-related functions to develop, maintain, and troubleshoot custom applications and adapters. | | operations / operator | Can create, manage, and execute Itential Platform automations and related workflow events. | | projectsadmin | Grants system-wide admin access to Studio Projects, so an admin can get, reassign membership on, or delete any Studio project regardless of their individual project-level permissions. Available only through the API. For more information, see [Project Admin role](/itential-platform/studio/projects/create-manage#project-admin-role). | | support | Grants access to perform support-related tasks on the system environment. | | taskread | Provides view-only access to task information, but does not allow you to make changes. | | taskwrite | Provides access to view task information and make changes. | ### FlowAI roles FlowAI uses application-level permissions to control access to agent projects, decorators, and agent sessions. These permissions are independent of project-level roles such as Owner, Editor, and Viewer, and must be explicitly assigned. For information about agent project-level roles, see [Agent Projects](/itential-platform/flowai/agent-projects#access-control). | Name | Source | Description | | :----------------------------- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent-projects:read` | AgentProjects | Grants access to the Agent Projects application. Agent Projects appears in the navigation only if you have this permission and at least one `agent-project-service` permission. | | `agent-project-service:read` | AgentProjectService | Access to all read-only Agent Project Service endpoints, such as get operable agents and get provider profiles. | | `agent-project-service:create` | AgentProjectService | Create resources, such as create agent, create agent project, and import a project bundle. | | `agent-project-service:update` | AgentProjectService | Update existing resources without creating or deleting them, such as update agent and update agent project. | | `agent-project-service:delete` | AgentProjectService | Delete existing resources, such as delete agent and delete agent project. | | `agent-project-service:admin` | AgentProjectService | Access to all `/admin/`-prefixed endpoints. Grants administrative access to every agent project regardless of project-level membership, so admins can manage orphaned or inaccessible projects. All actions are recorded in the audit log. | | `decorator:read` | ToolRegistry | View available decorators when creating or editing an agent, and export decorator definitions via API. | | `decorator:create` | ToolRegistry | Create, clone, and import decorator definitions. Available only in the API. | | `decorator:delete` | ToolRegistry | Delete decorator definitions via API. | | `session:read` | AgentSessions | Access to Agent Sessions. Required to view any session. Without this permission, Agent Sessions isn't visible in the UI. | | `session:manage` | AgentSessions | Pause, resume, and cancel sessions. Requires `session:read`. | | `session:delete` | AgentSessions | Delete sessions permanently, including the session record and audit trail. Requires `session:read`. | | `provider-profiles:read` | ModelRegistry | View all provider profiles in Model Registry. | | `provider-profiles:write` | ModelRegistry | Create and edit all provider profiles in Model Registry. | | `provider-profiles:delete` | ModelRegistry | Delete all provider profiles in Model Registry. | #### Grant FlowAI access FlowAI permissions span four applications: Agent Projects, Agent Sessions, Tool Registry, and Model Registry. Grant permissions for the application and action a user actually needs, rather than as a single bundle. For example, managing Model Registry profiles doesn't require any Agent Sessions permissions, and monitoring sessions doesn't require any Agent Projects permissions. **Agent Projects** | To do this | Grant | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Create and edit agents and projects, and view available decorators | `agent-projects:read`, `agent-project-service:read`, `agent-project-service:create`, `agent-project-service:update`, `decorator:read` | | Also create, clone, and delete decorators | `decorator:create`, `decorator:delete` | | Also manage any project regardless of membership, including orphaned or inaccessible ones | `agent-project-service:delete`, `agent-project-service:admin` | **Agent Sessions** | To do this | Grant | | ----------------------------------------------- | ---------------------------------- | | Monitor agent session activity | `session:read` | | Also pause, resume, cancel, and delete sessions | `session:manage`, `session:delete` | **Model Registry** | To do this | Grant | | -------------------------------------- | ----------------------------------------------------- | | View provider profiles | `provider-profiles:read` | | Also create, edit, and delete profiles | `provider-profiles:write`, `provider-profiles:delete` | ### Endpoints Endpoints are defined by each application in the Platform. There are two types: | Endpoint | Description | | :---------- | :-------------------------------------------------------------------------------------------------------- | | API Methods | Represent API endpoints that read or write data. | | UI Views | Represent web pages in the browser. A view will typically rely on one or more methods to read/write data. | To view endpoints granted to a role: #### Navigate to Roles Select **Roles** from the left-side navigation menu. A table list displays with a role for each application installed in the system. #### Search or filter Optionally, use the search bar to filter by role, application, or description. #### View role details Click the view icon for your desired role to open the **View Role** modal, which shows all **API Methods** and **UI Views** for a role. You can sort and filter using the **Method** and **Source** fields. ![](/_fern-img/282db7ce9b408d679ed35284ce7f4e2c88bb81d7739ea4851457de5d5ac4b89c.webp)![](/_fern-img/f11f6a9c8f36c63b57b6615de1146e164b6cc335e1fe776ecd90d9ab901a1e9a.webp) ## Custom roles In addition to built-in roles, administrators can define custom roles for different authorization strategies. Built-in roles are hard-coded in the services and can't be edited. Users can only use services from their active server profile and can't add roles for services that aren't currently running. ### Create a custom role #### Open the Create dialog Click the plus (+) sign from the top toolbar in Admin Essentials to open the **Create** dialog. #### Select Role Select **Role** from the dropdown menu. #### Enter name and description Give the new custom role a unique name (required) and a description (optional). #### Assign endpoints Select the appropriate API endpoints and UI views in the **Edit Role** modal, then click **Save**. The custom role appears in the **Authorization: Roles** table view and displays as `Custom` under the **Type** column. ![](/_fern-img/781108c6679a8c3a3f9e8c2f8d16fc293f50f3c204fac8558e3c7026c60cd022.webp)![](/_fern-img/dc619ccfcdb6b67fb5014bf0066edd15abeff87d7c92c74a427a7b61f153fc9d.webp) ### Edit custom role permissions #### Navigate to Roles Select **Roles** from the menu in the left navbar. #### Find the custom role Type the name of the **Custom** role in the search bar under the **Role** column header and select it from the results. #### Open Edit Click the stacked dots menu icon and select **Edit**. The endpoints for the selected custom role display in the **Edit Role** modal, with tabs for API Methods and UI Views. #### Update the role Update the role name or description if needed. Locate the permissions you want to grant or remove. Filter the list by typing in the search box, then add or remove permitted endpoints by selecting the checkbox. #### Save Click **Save** to finalize your changes. ![](/_fern-img/319810fd27be4affe74a05d2acf61e7a0c9e87651cd14bfc9bc9d4a2cbfd41ae.webp) ### Delete a custom role This is a hard delete. Deleting a custom role removes it from all users and groups that have it assigned. Only custom roles can be deleted. #### Locate the custom role Locate the custom role you want to delete. Filter the list using the filter fields in the column header. #### Delete Click the stacked dots menu icon and click **Delete** for the role. #### Confirm Verify that the custom role no longer appears in the Roles table. ## Export authorization data You can export a list of Users, Groups, and Roles from the **Authorization** interface to a CSV file. Use the CSV as a reference to track user roles and group memberships. To use this export feature, you must have permissions to read and write roles on users and groups, and permission to perform the export. #### Navigate to Authorization Navigate to **Admin Essentials** → **Authorization**. #### Export Click the export icon. A confirmation dialog displays. #### Download Click the **Download** button. A CSV file downloads to your system. #### Open the file Go to the location where the CSV file is saved and open it in your spreadsheet application of choice (e.g., Microsoft Excel, Google Sheets, Smartsheet). ![](/_fern-img/9f0123122f55e7d210b6125b6ba007948de62286ad87300876ebc61fc84ade61.webp)![](/_fern-img/f7eb6b4f27b0aba34e5b16e6afa31a7f5b9078ff8ecb5a02e0ad5f31779d0aca.webp) | Column Header | Description | | :------------ | :---------------------------------------------------------------------------------------- | | User ID | Identifier of the user account. | | Provenance | The name of the AAA the user comes from. | | Username | The unique name of the user account. | | First name | The user's first name. | | Email | The email address associated with the user account. | | Last Login | The last date and time of login. | | Active | A boolean indicating if the user account is active (true/false). | | Groups Names | A list of group names to which the user belongs. Each group name includes its provenance. | | Roles Names | A list of roles assigned to the user. | ## Service accounts The **Clients** view lists clients for service accounts. Click a client to open its details page, which shows the **Client ID** and a timestamp for when the client secret was generated. Use the toggle at the top to enable or disable the service account. Disabled service accounts can't authenticate. For security, editing a service account client requires the `service-accounts:read` and `service-accounts:write` roles. To grant users the ability to edit service account client permissions, enable these roles in the relevant groups. ![](/_fern-img/85f4f0768aa98c6befbd95a1e2b6c7f31be08956e13e3b826e9e89d0ea1f61b0.webp)![](/_fern-img/1efd4574114388a9e90e92aa325bca978d77510fca755ec4eed71191314cf259.webp) Applications that need a point of entry to interact with Itential Platform APIs are created as **Service Accounts** in Itential Platform. Using OAuth2 protocols over HTTPS, authorization policies and controls are applied to limit what the requesting application is permitted to do and for how long. The client ID identifies the service account and the secret key provides proof of right-to-access. The client ID and secret key may be distributed to one or more service applications. Using service accounts to encapsulate applications provides a more secure connection to external systems, uses tokenization to limit access to user data, protects credentials by sharing a client token ID instead of user credentials, and lets third-party services make requests on behalf of users without accessing passwords or other sensitive information. ### Service account properties | Parameter | Type | Description | | :------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------- | | name | string | The specific name associated with the service account. | | description | string | A brief description of the service account for the external system. | | client\_id | string | Auto-generated by Itential Platform; can be copied by the administrator. | | client\_secret | string | Auto-generated by Itential Platform; can be copied by the administrator. | | grant\_type | string | A JSON Web Token (JWT) providing the service application authenticated access to Itential Platform for a set amount of time. | **Example service account configuration:** ```json "accountData" : { "name": "Service Account Hello", "description": "This is a service account", "client_id": "638e17011ba61d5e222a16ab", "client_secret": "94367284-b12a-4858-b6c1-0bb11f1f126b", "grant_type": "xxxxx.yyyyy.zzzzz" } ``` ### Service account APIs | API | Description | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createServiceAccount` | Creates a service account in the Mongo database. | | `getServiceAccounts` | Returns the service account based on query parameters, but does not include `clientSecret` in any returned data. This is a one-time value generated once a service account is created and never generated again. | | `updateServiceAccount` | Updates the service account `description`. | | `deleteServiceAccount` | Deletes the linked service account from the accounts collection. | ### Error responses | Error Code | Description | | :--------- | :------------------------------------------------------------------------- | | 400 | Unable to authenticate; grant-type unsupported or client secret incorrect. | | 409 | Duplicate service account is not allowed. | | 415 | Unsupported format type for the HTTP method used. | | 500 | Missing parameters; failed to call adapter route for service\_name. | ### Create a new client for a service account #### Open the Create dialog Click the **+** sign on the toolbar to open the global **Create** dialog. #### Select OAuth Client Select "OAuth Client" from the dropdown menu list. #### Enter details Input a unique client name and a brief description, if desired. ![](/_fern-img/f9ecf08b8bfba043722e5e0e1c0da7c8438f0052b7af684db77a76cecc4639c2.webp) #### Save Click **Save**. The **Authorization Client Details** page opens with the **Client Secret** visible for copying. A timestamp shows when the secret was generated. ![](/_fern-img/389a35e07d1ae34d392564ebfa09590f0fa6e990d1a927a08dc6ef1676fccb50.webp) #### Save the secret A bold message reminds you to save the client secret. If you lose the secret, click **Regenerate** to create a new one; this invalidates the previous secret. ![](/_fern-img/1e63170bf0a2cc505ee1dc841ac028e8d51c5d45b2a8a100b1c6551c609635c8.webp) If you leave the **Authorization Client Details** page and return later via the Clients Collection view (Admin Essentials → Authorization → Clients), the client secret is no longer visible, only the timestamp. ![](/_fern-img/b2928ae92de535b11929a0fea0120275120354f3a05f9589e85d21ee218abc03.webp) ### Edit client permissions for service accounts #### Open Edit Permissions From the **Clients Authorization Details** page, click the **Edit Permissions** button. The **Edit User** dialog displays. ![](/_fern-img/291656d69c40733c6859a20e3be0b618f6fa650d7b56495ddf8b6353c1c2b552.webp) #### Assign roles Select the appropriate user role permissions to assign. #### Save Click the **Save** button to retain your changes. ![](/_fern-img/c6e8feafb6a4f61a2a4d7c038283c96ff3cd0e99686555d12ab487afb7c47f8c.webp) ### Enable and disable clients for service accounts Use the toggle at the top of the **Client Details** page to enable or disable the service account, then click **Save**. A message banner confirms the state change. Disabled service accounts can't authenticate. ![](/_fern-img/064fc95b8d8907eaae1d5b3b4b207f0f107b5ecd657fa5cfe86ffe7d4c5e670f.webp)![](/_fern-img/d477c11052a74c4083d3c124f35f094640b2c2692604d347a096a1b85ac2262a.webp) ### View, edit, and delete service accounts To view all service accounts, select **Users** from the left navigation menu in Admin Essentials, then click the **Service Accounts** tab. Click the pencil icon to edit a service account's permissions. ![](/_fern-img/2754065a7503bcd666fa2c7953ca260037b6ee5801ab271eb95be46d4b45d4b1.webp) To delete a client, click its name in the Clients list to open the **Client Details** page. Click the menu button (⋮) in the upper-right corner and select **Delete**. ![](/_fern-img/f66e9aa4e642978371d8864334ad6672a41fc9813309398d9aec6b8aeb4d8ed6.webp)![](/_fern-img/d7a54e4cc5765f54c88379bf8d5fb767b86aadf372da02f84e1d3969fa13acbb.webp) ### View and modify client metadata for service accounts From the menu button (⋮) in the upper-right corner of the **Client Details** view, select **Metadata**. The metadata drawer shows a **Created** timestamp and the **user** who created or last updated the client. Click **Close** to dismiss. ![](/_fern-img/71a4595a4767f5858e04c5191c7e2e07524e1acf7b653eb882264311da892897.webp) ### Use OAuth2 in Postman After creating a service account client, you can use its `client_id` and `client_secret` to authenticate Itential Platform API calls in Postman without a username or password. There are two ways to set this up: using a pre-request script or using a curl command. #### Use a pre-request script #### Add the pre-request script In Postman, open the **Pre-request Script** tab and paste the following script. Replace ``, ``, and `` with the values from your service account client. ```js const postRequest = { url: 'https://:3443/oauth/token', method: 'POST', timeout: 0, header: { "Content-Type": "application/x-www-form-urlencoded" }, body: { mode: 'urlencoded', urlencoded: [ {key: 'client_id', value: ''}, {key: 'client_secret', value: ''}, {key: 'grant_type', value: 'client_credentials'}, ] } }; pm.sendRequest(postRequest, function (err, res) { var responseJson = res.json(); console.log(responseJson.access_token); pm.globals.set('authToken', responseJson.access_token); }); ``` #### Set the authorization type On the **Authorization** tab, set the **Auth Type** to **Bearer Token** and enter `{{authToken}}` as the token value. ![](/_fern-img/45cff5216147a8f3bcecd1c7216c462869ee7b2f7bd99ae081196c8754a4858e.webp) #### Send the request Send any API request. Postman runs the pre-request script first, retrieves a token, and attaches it automatically to the request. #### Use a curl command #### Import the curl command In Postman, select **Import** and paste the following curl command. Replace ``, ``, and `` with your values. ```bash curl --location 'https:///oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ --data-urlencode 'grant_type=client_credentials' ``` #### Configure the request Select **POST** as the method, then go to **Body** and select **x-www-form-urlencoded**. #### Send and verify Send the request. The response includes a `token_type` of `bearer` and an `access_token` you can use in subsequent API calls. ![](/_fern-img/9996a38ed23b22b2e926c9633ad37ca7e5fb37c37c57abfc280252fb98b8c366.webp) > How to manage users, groups, roles, and service accounts through the Authorization interface in Admin Essentials.