Organizations and access

Configure roles and permissions

Create custom organization roles and verify the effective organization and skill permissions for a member.

Create a custom role for an organization, then verify what the current member can do. This API workflow is useful when an administrator needs more precise grants than the built-in OWNER, ADMIN, MEMBER, and VIEWER roles provide.

⚠️Custom role permissions are additive. They can grant capabilities beyond a member's built-in role, but they cannot remove capabilities that the built-in role already provides. A custom role also cannot grant organization deletion.

Before you begin

You need an authenticated Agent Studio session, the target organization ID, and permission to manage roles. The management routes use the signed-in session; an organization API key is not a substitute for that session.

The examples use these local shell variables:

bash

export AGENT_STUDIO_URL="https://studio.example.com"
export ORGANIZATION_ID="org_example"
export SESSION_COOKIE="__session=replace-with-your-session-cookie"

Treat the session cookie as a secret. Do not save it in source control or shell history.

How permissions combine

The effective organization permission set starts with the built-in role and overlays member and custom-role grants. Skill permissions use the hierarchy SKILL_VIEWER, SKILL_EXECUTOR, SKILL_EDITOR, and SKILL_ADMIN; a higher permission satisfies the lower levels. Organization owners and administrators have full skill access inside their organization.

Create and verify a role

Inspect existing roles

List the organization's custom roles before choosing a name:

bash

curl --fail-with-body \
  --cookie "$SESSION_COOKIE" \
  "$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/roles"

A successful response has success: true and a data array. Check the existing names and permissions to avoid creating overlapping roles.

Choose additive grants

Define the extra capabilities the member needs. For example, a support workflow operator might need skills:execute, executions:create, and audit:read without full organization administration.

Use only supported permission strings. Common organization grants include members:manage, org:manage, skills:create, skills:execute, executions:create, audit:read, vault:create, api_keys:manage, and roles:manage. Skill-level membership grants use the SKILL_* names described above.

Create the custom role

Send a role name of 1–50 characters, an optional description of up to 500 characters, and at least one permission:

bash

curl --fail-with-body \
  --request POST \
  --cookie "$SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Workflow operator",
    "description": "Runs skills and reviews execution activity",
    "permissions": ["skills:execute", "executions:create", "audit:read"]
  }' \
  "$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/roles"

Agent Studio returns HTTP 201 with the created role in data. Record its id; later requests use it as ROLE_ID.

Review or adjust the role

Read the role with GET /api/organizations/{organizationId}/roles/{roleId}. If a grant is missing, replace the relevant fields with PUT:

bash

curl --fail-with-body \
  --request PUT \
  --cookie "$SESSION_COOKIE" \
  --header "Content-Type: application/json" \
  --data '{"permissions":["skills:execute","executions:create","audit:read","skills:read"]}' \
  "$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/roles/$ROLE_ID"

The response returns the updated role in data. An omitted field remains unchanged; an explicitly supplied permissions array replaces that role's stored array.

Verify effective permissions

After the role is assigned to the member through your organization membership workflow, ask that member to call:

bash

curl --fail-with-body \
  --cookie "$SESSION_COOKIE" \
  "$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/permissions"

The response reports the current member's base role, effective organization permissions, and membership skillPermissions. Verify the capabilities, not only the custom role definition: built-in permissions remain effective.

✅The configuration is verified when the member's permissions response contains the expected effective grants and the member can perform the intended action without receiving a role or permission error.

Remove a role

When a custom role is no longer needed, first move affected members to an appropriate role, then delete it:

bash

curl --fail-with-body \
  --request DELETE \
  --cookie "$SESSION_COOKIE" \
  "$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/roles/$ROLE_ID"

The route returns data.deleted: true after removal.

Troubleshooting

Next steps

Review organization members before assigning broad grants, or configure skill permissions for skill-specific access.