Working with Roles

This section describes about creating roles and users for the Protegrity Agent on a Protegrity Policy Cloud cluster. Roles define the features that a user can access. Users inherit permissions from their assigned roles.

For more information about permissions, refer to Required Roles and Permissions.

Prerequisites

A running PPC cluster with the Protegrity Agent deployed.
kubectl is configured and is accessible for the target PPC cluster.
An admin account on the PPC cluster with required permissions to create roles and users.

Retrieving the Gateway Host

To store the PPC gateway address in a shell variable, run the following command .

export GW_HOST="$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')"

The GW_HOST variable is used in every subsequent command.

Generate a JWT Token

Ensure to authenticate as the PPC admin user to obtain a JSON Web Token (JWT). All role and user creation commands require this token.

TOKEN=$(curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:' \
  | sed 's/pty_access_jwt_token: //' \
  | tr -d '\r') && echo "${TOKEN:0:10}"

A successful response prints the first 10 characters of the token. If the output is empty, verify the admin credentials and gateway address.

Creating Agent Roles

Create one or more roles that bundle the permissions that are required by the users.

This section provides two recommended role skeletons:

Administrator with complete access permissions
Viewer with read-only permissions

Complete-Access Role (agent_admin)

This role grants read-write access to all Agent, Workbench, and Insight features.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_admin",
    "description": "Administrator role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_certificate_export",
      "workbench_package_export_dynamic",
      "workbench_package_export_encrypted",
      "workbench_policy_manage",
      "workbench_policy_view",

      "insight_admin",
      "insight_viewer",

      "can_create_token"
    ]
  }'

This user inherits all permissions from the agent_admin role.

For more information about the available permissions for agent_admin, refer to Roles.

Read-Only Role (agent_reader)

This role restricts access to read-only operations. The user can view conversations and policies but cannot modify or export them.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_reader",
    "description": "Read-only role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_policy_view",

      "insight_viewer",

      "can_create_token"
    ]
  }'

This role excludes workbench_policy_manage, all package export permissions, and insight_admin. The user can view policies and the Insight dashboard but cannot make changes.

For more information about the available permissions for agent_reader, refer to Permissions.

Building a Custom Role

To create a role with any subset of the available permissions, select the required permission from Protegrity Agent Permissions Reference . The JSON payload follows the same structure shown above. Replace the name, description, and permissions array with your values.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name of custom the role>",
    "description": "<description custom the role>",
    "permissions": [
      <permission 1>,
      <permission 2>,
      <permission 3>
    ]
  }'

Validate Role Creation

To list all roles and confirm your new roles exist, run the following command .

curl -sk -X GET "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

The response includes every role on the PPC cluster. Ensure that agent_admin and agent_reader roles appear in the list.

Create Agent Users

Create user accounts and assign them to the required roles.

Admin User

This user inherits all permissions from the agent_admin role. To create an agent_admin, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_admin",
    "email": "agent_admin@example.com",
    "firstName": "Agent",
    "lastName": "Admin",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_admin"
    ]
  }'

Read-Only User

This user inherits the read-only permissions from the agent_reader role. To create an agent_reader, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_reader",
    "email": "agent_reader@example.com",
    "firstName": "Agent",
    "lastName": "Reader",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_reader"
    ]
  }'
```=

#### User Skeleton Structure

Every user creation request follows the same JSON structure.

```json
{
  "username": "<unique-username>",
  "email": "<email-address>",
  "firstName": "<first-name>",
  "lastName": "<last-name>",
  "enabled": true,
  "password": "<password>",
  "roles": [
    "<role-name-1>",
    "<role-name-2>"
  ]
}

Field	Description
`username`	Set a unique identifier for the user account
`email`	Set the email address associated with the user account
`firstName`	Set the first name of the user
`lastName`	Set the last name of the user
`enabled`	Enable or disable the user account; set to `true` to activate
`password`	Set the initial password for the user account
`roles`	Assign one or more roles that define the permissions this user receives

A user can hold multiple roles. The effective permission set is the union of all permissions from every assigned role. For example, assigning both agent_reader and a custom role that includes workbench_policy_manage grants the user both read and write access to policies.

Note: Change the default passwords before deploying to a production environment.

Verify the User Configuration

After creating the users, log in with the new credentials to confirm the accounts are accessible.

curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=agent_admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:'

A successful response returns a pty_access_jwt_token header. An empty response indicates incorrect credentials or a missing role.

Feedback

Was this page helpful?

Last modified : April 09, 2026