Agent Capabilities
How agents get permissions — capability-based scoping via agent-auth
Agent Capabilities
The NextPay CLI no longer uses API keys (npk_*). Instead, agents are authenticated via the agent-auth flow and receive capabilities based on the role of the user who approved them.
How capabilities work
When a user approves a CLI agent through the device authorization flow, the identity service grants the agent a set of capabilities derived from the user's role in the organization. The agent can only perform actions that:
- The user's role permits, and
- Are within the organization and workspace specified at login time.
There is no separate key to create, scope, or revoke. Permissions follow the user.
Inspecting capabilities
To see what a registered agent is allowed to do, call the capabilities endpoint:
GET /v1/agent/capabilities
Authorization: Bearer <signed-jwt>The response lists each granted capability, e.g.:
{
"agentId": "agent_abc123",
"capabilities": [
"workspace:read",
"directory:read",
"directory:write",
"disbursement:create"
]
}Controlling agent permissions
To restrict what an agent can do, adjust the user's role in the NextPay dashboard:
- Go to Settings > Team.
- Find the user whose session the agent was approved under.
- Change their role to the minimum required for the agent's tasks.
| Agent purpose | Recommended role |
|---|---|
| Read-only reporting | viewer |
| Directory management | directory_manager |
| Full payout operations | disbursement_manager |
| Administrative automation | admin |
Revoking agent access
To revoke a specific agent's access, revoke the agent from the identity service:
DELETE /v1/agent/<agentId>This immediately invalidates all future JWTs signed by that agent's private key, even if the key file still exists locally. The user's other approved agents are not affected.
To log out on the CLI side (which also deletes the local key):
nextpay --env prod auth logout