Give people access to agents and skills

> Who this is for: administrators who need operators and viewers to see and use specific agents. You will have a team, its members, and a grant that lets the team work with one skill of one agent, plus a way to check and revoke it.

A new operator or viewer sees nothing. Their role sets the most they may ever do; a grant decides which agents, or which skills of an agent, they may do it on. You give grants in Settings, or with the access management API. Administrators need no grants: they see and operate every agent in their organization.

Agent Taskbay is pre-1.0. The screens and API on this page may change between minor versions.

Before you startCopy Anchor Link

• You are signed in as an admin. Only administrators see the Teams and access section and can call /api/admin/security.
• The people already have a membership in your organization, provisioned with npm run auth:provision (see Sign in and roles). Only enabled memberships appear in the lists.
• The agent is registered and its card has been discovered. The skill list in Settings comes from the agent's stored card. If it shows only Whole agent, open the agent on the Agents page so its card loads.
• For a skill-only grant that people can use to send work, the agent must advertise the skill-routing extension https://extensions.allsrc.dev/agent-taskbay/skill-routing/v1 and list the skill id in its card. See the skill routing reference. Without it, only whole-agent grants let people send.

How roles and grants combineCopy Anchor Link

A grant names a recipient, an agent, an optional skill, and a permission. The recipient is everyone in the organization, one person, or one team.

Grants add up. A person gets the union of their own grants, their teams' grants, and the organization-wide grants. A whole-agent grant covers every skill of that agent. A skill grant covers only that skill.

Approvals follow the same rule. Deciding an approval on a task that belongs to a skill needs operate on that skill.

The rules are in access-policy.ts and tested in scoped-security.test.ts and scoped-security.db.test.ts.

Example: give the Payments team operator access to the refunds skillCopy Anchor Link

In this example the agent is named "Billing agent" and has a skill named "Refunds". Two operators, Ada Lovelace and Alan Turing, should send refund requests to it, and nothing else.

Create the teamCopy Anchor Link

1. Open Settings. Find the Teams and access section.
2. In Team name, type Payments.
3. Select Create team.

Add membersCopy Anchor Link

1. In Choose team, select Payments.
2. In Choose member, select Ada Lovelace (operator).
3. Select Add member.
4. Repeat for Alan Turing (operator).

Each member appears as a row such as Payments · Ada Lovelace. Adding the same person twice has no effect.

Grant the skillCopy Anchor Link

1. In the grant form, set the recipient to Team: Payments. The other choices are Everyone in organization and each person by name.
2. In Choose agent, select Billing agent.
3. In the scope list, select Refunds. Leave it on Whole agent to grant every skill.
4. In the permission list, select Read and operate. Select Read instead for look-only access.
5. Select Grant access.

The grant appears as a row: Payments · Billing agent · refunds · operate. The third field is the skill id, or whole agent.

Do the same through the APICopy Anchor Link

The Settings form calls POST /api/admin/security. You can send the same bodies from a browser session. A script must send the session cookie and, in OIDC mode, an Origin header equal to A2A_AUTH_ORIGIN (see HTTP API).

Read the IDs of teams, memberships and grants with GET /api/admin/security. It returns { organizationId, teams, memberships, teamMembers, grants, credentials }.

Create the team:

{ "action": "createTeam", "name": "Payments" }

Add a member:

{ "action": "addTeamMember", "teamId": "TEAM_UUID", "membershipId": "MEMBERSHIP_UUID" }

Grant one skill:

{ "action": "grant", "subjectType": "team", "subjectId": "TEAM_UUID", "agentId": "AGENT_UUID", "skillId": "refunds", "permission": "operate" }

Use "skillId": null for the whole agent. For everyone, use "subjectType": "organization" with your organizationId as subjectId. For one person, use "subjectType": "membership" with their membership ID. Each success returns { "updated": true }. The full list of actions is in the HTTP API reference.

Check the resultCopy Anchor Link

1. In Settings, the grant row shows the recipient, agent, skill and permission. Only enabled grants are listed.
2. Ask a team member to sign in and open Agents. They see Billing agent with the description Restricted skill access and only the Refunds skill. The other skills, and the agent's own description, are hidden.
3. When they start a task with that agent, the chat shows a Skill picker with only the granted skills. Taskbay sends the skill id to the agent in the skill-routing metadata.
4. Their task lists show only tasks recorded for that skill.
5. The Audit page records each change: team.created, team.addTeamMember, access.granted.

A member with a skill grant cannot send to the agent without a skill, cannot pick another skill, and cannot continue an arbitrary existing context. Those sends fail with 403 (see the table below).

Revoke accessCopy Anchor Link

To revoke a grant, select Revoke on its row in Settings, or send:

{ "action": "revokeGrant", "grantId": "GRANT_UUID" }

To take one person out of a team, select Remove on their Payments · Name row, or send removeTeamMember with the teamId and membershipId. They lose the team's grants but keep any grants made to them directly or to the whole organization.

To switch off a whole team, send:

{ "action": "disableTeam", "teamId": "TEAM_UUID" }

All of the team's grants stop applying. There is no button for this in Settings.

Revocation applies to the person's next request. A revoked grant is disabled, not deleted, and the change is audited as access.revoked. Work Taskbay has already accepted into the worker continues.

When it failsCopy Anchor Link

Errors from Settings appear as a red message above the forms.

LimitsCopy Anchor Link

• A skill grant relies on the agent. Taskbay picks the skill and sends it, but cannot check that the agent enforces it. Use skill grants only for agents whose enforcement you have reviewed. See the skill routing reference.
• The skill id is not checked when you create the grant. A grant for a skill the card does not list is accepted, and sends under it fail with This agent does not support bounded skill routing.
• The same grant can be created twice. Each copy is a separate row, and revoking one leaves the other in force. Check the list before granting again.
• Teams cannot be renamed, deleted or re-enabled. Disabling is API-only. A disabled team still appears in the grant and member rows in Settings, but its grants do not apply.
• A grant on an admin is accepted and has no effect.
• There is no CLI for teams or grants, and no sync from identity-provider groups. Provider group and role claims grant nothing.
• Teams cannot be escalation targets.
• One organization per deployment.

RelatedCopy Anchor Link

• Sign in and roles
• Identity and access
• Skill routing extension
• HTTP API: access management
• Use the console: where grants take effect, screen by screen.