Skills and workflows

Configure skill permissions

Inspect role-derived skill access and submit supported permission assignments for organization members.

Inspect the effective access to an organization-owned skill and submit a supported permission set for a member. Agent Studio currently derives the returned access from organization roles, so use this workflow to validate access without assuming that a per-skill override persists.

Before you begin

Sign in as an organization OWNER or ADMIN to submit or reset an assignment. The skill must belong to an organization, and the target user must already be a member of that organization. Record the skill ID and target user ID from your own environment.

⚠️The current permission endpoint acknowledges assignment and reset requests but does not maintain a dedicated per-skill permission record. A later read continues to report access derived from organization roles. Manage durable access through organization membership and roles.

Choose supported permissions

The assignment endpoint accepts only these exact values:

Permission	Intended access level
`SKILL_ADMIN`	Administrative control of the skill
`SKILL_EDITOR`	Editing access
`SKILL_EXECUTOR`	Execution access
`SKILL_VIEWER`	View access

The effective-access response maps organization roles as follows: OWNER and ADMIN receive all four permissions; MEMBER receives editor, executor, and viewer access; other organization roles receive viewer access. A skill owner and a super administrator also receive all four permissions when access is evaluated.

Inspect and configure access

Read effective access

Request the permission list for the organization-owned skill from a same-origin authenticated client:

const response = await fetch("/api/skills/skill_example/permissions", {
  credentials: "include",
});
const result = await response.json();

if (!response.ok || !result.success) {
  throw new Error("Could not read skill permissions");
}

The data array identifies each organization member with userId, userName, userEmail, orgRole, and skillPermissions. Save the target member's userId; do not substitute an email address in later requests.

Compare access with the role

Check the member's orgRole and returned skillPermissions against the role-derived mapping above. This establishes the effective starting state and helps you detect a membership issue before submitting a change.

If the skill has no organizationId, the route returns Skill does not belong to an organization. Add the skill to the correct organization through the supported skill-management workflow before continuing.

Build the permission set

Choose the smallest set needed for the member's work. For a workflow author who must edit, run, and inspect a skill, a supported request body is:

json

{
  "targetUserId": "user_example",
  "permissions": [
    "SKILL_EDITOR",
    "SKILL_EXECUTOR",
    "SKILL_VIEWER"
  ]
}

Use only the four exact permission names. The endpoint rejects any unrecognized value and requires both targetUserId and permissions.

Submit the assignment

Post the selected values as an organization owner or administrator:

const response = await fetch("/api/skills/skill_example/permissions", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    targetUserId: "user_example",
    permissions: ["SKILL_EDITOR", "SKILL_EXECUTOR", "SKILL_VIEWER"],
  }),
});

const result = await response.json();
if (!response.ok || !result.success) {
  throw new Error("Permission assignment was rejected");
}

A successful response echoes the target user and requested permissions. Treat this as an acknowledged request, not proof of a stored per-skill override.

Recheck effective access

Repeat the initial GET request. Confirm the member remains present and interpret the returned permissions from the member's organization role.

If durable access must change, update the member's organization role using Configure roles and permissions, then repeat this check.

Reset to organization defaults

An owner or administrator can submit a reset request with the target user ID as a query parameter:

const targetUserId = encodeURIComponent("user_example");
const response = await fetch(
  `/api/skills/skill_example/permissions?targetUserId=${targetUserId}`,
  { method: "DELETE", credentials: "include" },
);

The success message states that permissions were reset to organization defaults. Read the permissions again to confirm the role-derived result.

Verify access

✅The target user appears in the GET response, the listed organization role is correct, and skillPermissions matches the role-derived access. The POST or DELETE response has success: true; no claim of a persistent per-skill override is required for verification.

Troubleshoot permission requests

Next steps

Use Manage organization members to correct membership, or Configure roles and permissions to make a durable role-based access change.