Status: Partially available

Grant and inspect permissions

Grant a role to give a principal more access, revoke it to take access away, and read the audit log to confirm what the server decided. Every command here changes access for the whole tenant; roles are not scoped to a space.

Prerequisites

• A credential with the admin role, such as the tenant admin_credential from Deploy Wyrd for a team, or the key wyrd server dev saved.
• The principal’s ID. wyrd principal list shows it.

If you are not sure which role you need, Identity and authorization lists what each built-in role allows.

1. Find the principal and its roles

The CLI uses your saved endpoint, or --server / WYRD_SERVER_URL:

wyrd principal list --kind service
wyrd principal role list --principal <principal-id>

A Service or Agent principal created by wyrd declare starts with workload. A tenant administrator holds admin.

2. Grant or revoke a role

wyrd principal role grant --principal <principal-id> --role editor
wyrd principal role revoke --principal <principal-id> --role editor

The same call from an SDK:

from wyrd.auth import Principals

principals = Principals()
result = principals.grant_role(principal_id, "editor")
print(result["changed"], result["roles"])

use wyrd_ai::auth::Principals;

let principals = Principals::connect().await?;
let result = principals.grant_role(&principal_id, "editor").await?;
println!("{} {:?}", result.changed, result.roles);

import { Principals } from "wyrd-ai";

const principals = await Principals.connect();
const result = await principals.grantRole(principalId, "editor");
console.log(result.changed, result.roles);

A grant is idempotent: granting a role the principal already holds returns changed: false and the unchanged role list.

The change reaches a running service within 5 minutes, when its access token is next renewed. Revoking a role that a person also gets from an identity-provider group does not remove it; change the group mapping instead.

3. Cut a principal off

To stop a principal entirely, suspend it:

wyrd principal revoke <principal-id> --kind service --reason "credential leaked in CI logs"

New tokens are refused at once, and tokens already issued expire within 5 minutes. To stop one credential but keep the principal, revoke just that credential with the principals.revoke_credential MCP tool.

4. Confirm the decision

Every permission check is recorded in the audit log. To see what was refused recently:

SELECT created_at, sub_principal_id, permission, outcome
FROM vala.system.audit_log
WHERE outcome = 'denied'
ORDER BY created_at DESC
LIMIT 20

Run it with any SDK’s Bifrost.sql, or the bifrost.query MCP tool. A refused call returns WYRD_PERMISSION_403_DENIED_RBAC, and the error names the permission the principal lacked.

What can go wrong

Last updated October 18, 2026