Permissions and roles

What this is: the permission keys, the seeded roles, and the rules that narrow a key (plan, billing state, assurance). Who it is for: tenant admins who must answer "who may do this, and why was this person refused?". You will learn: how keys are named, what each system role holds, how a plan removes a key, and how comp access works.

How keys are named

Code names keys, never roles. A key is area.thing or area.thing.verb. A trailing .* marks a family (gateway.tool.<name>, model.role.<alias>). Platform keys use a dot (platform.kill_switch); one uses a colon (platform:grant_complimentary). Each key carries: A trailing .* marks a family (gateway.tool.<name>, model.role.<alias>). Platform keys use a dot (platform.kill_switch); one uses a colon (platform:grant_complimentary). Each key carries:

• On: the kind of object it is checked on (tenant, agent, binding, channel, board, device and so on).
• Assurance: the weakest sign-in strength allowed: none, weak, linked, strong, strong_mfa.
• Plan gate: empty, a plan name (that plan or higher), or entitlement:<name> (the plan must grant it).
• Class: read, write, admin or platform. Writes in chat can carry an obligation (see below).

Keys starting platform. belong to Bill and Ben staff and are not available to customers.

Which permission lets a person command Ben?

agent.command on the Ben binding. agent.ask only lets Bill or Ben answer questions with read tools. Then each tool needs its own key: code.push for branches and pipelines, ado.write and ado.comment for Azure DevOps, target.sandbox.use for sandbox work, target.device.use for a device. A person with agent.command but not code.push can start a task, and Ben still cannot push for them.

Seeded roles

Seven roles are copied into each new tenant. A role is a list of keys or prefix.* patterns. Admins may edit them in the admin console; custom roles are a plan feature (custom_roles). The last Owner cannot be removed.

Role	Holds
owner	console.*, agent.*, meeting.*, channel.*, canvas.*, target.*, code.*, ado.*, gateway.*, knowledge.*, model.*, admin.*, audit.*, privacy.*, billing.*, usage.*, tenant.grant_complimentary
admin	admin.*, audit.view, usage.view, and the console pages for users, roles, agents, channels, usage, audit, privacy, devices, knowledge, gateway
billing_admin	billing.*, usage.view, console pages for billing and usage
developer	agent.ask, agent.command, target.sandbox.use, target.device.*, ado.comment, ado.write, code.push, canvas.board.*, canvas.plan.execute, knowledge.search, gateway.connect
ops	like member, plus target.server.run_script and target.device.use
member	agent.ask, agent.command, target.sandbox.use, ado.comment, canvas.board.*, knowledge.search, gateway.connect
viewer	agent.ask, canvas.board.view

Every role also holds usage.view_own (Owner through usage.*), so each person sees their own usage on the Home page. Platform keys are never in a seeded role. Operators in tenant #1 hold them through their own grants. canvas.plan.execute is a key, not a fixed rule: an admin can give it to any role.

Order of checks

The permission check runs these in order and stops at the first refusal. The reason is returned to the caller.

Step	Refuses with	When
Subject	unknown_subject	not an active user of a known tenant, or a service or anonymous caller
Kill switch	tenant_suspended	platform or tenant kill switch is on (platform keys are exempt)
Tenant and billing state	tenant_suspended, tenant_restricted	tenant not active; restricted or read_only allows reads only
Platform scope	no_permission	a platform key from outside tenant #1
Agent state	no_permission, agent_paused	agent missing or disabled; paused agents allow only agent.pause and agent.configure
Plan gate	plan_feature_missing, quota_exceeded	the effective plan lacks the entitlement, or its monthly quota is used
Assurance	weak_identity	sign-in weaker than the key needs
Role and grants	no_permission	no role, group or direct grant gives the key
Failure	pdp_unavailable	any error, timeout or bad answer

After OpenFGA, obligations may be attached to an allow:

• confirm_out_of_band: a write or admin key asked from a chat or voice channel needs an approval card first.
• summary_only: a gateway call without gateway.detail.full may only return summaries.

Plan gates and entitlements

The effective plan for a person is the best of: a complimentary grant for them, a tenant-wide grant, or the live subscription. Admin overrides win over plan values. Entitlement names in the seeded plans: meeting_minutes, sandbox_minutes, server_scripts, gateway (summary or full), model_roles, devices, custom_agents, custom_roles, sso, scim, audit_export. Numbers are per user, so the quota is the number times the seats, and -1 means unlimited. For model.role.<alias> the alias must be in the plan's model_roles list. What each plan includes: Plans and billing.

Complimentary access

Staff can give a tenant or one user a plan at no charge. Rules:

• The key is platform:grant_complimentary. Grants, changes and revokes are checked again and audited.
• A grant has a reason and may have an end date and a model-spend budget. Spend caps still apply: the grant's budget counts toward the team spend cap.
• Staff can delegate the right by assigning the platform role comp_grantor. A delegate cannot delegate further.
• tenant.grant_complimentary is the scoped version: a tenant's own Owner may comp the tenant's own users, if the platform allows it.
• Bill and Ben staff hold a permanent grant for their own tenant.

Run grants: who is asking while an agent works

When an agent starts work for you, it receives a temporary pass for that run. The pass is tied to you, your tenant, the agent and the place you asked from, and may be narrower than your own rights: it lists the only permissions the run may use, even if you could do more. The model never says who is asking. Without a valid pass the agent cannot use a tool, and a tool outside the pass is refused too. The pass lasts at most 12 hours. When one agent hands work to the other, the pass handed on is never wider than the original and is shorter-lived. A pass you revoke stops working within seconds.

Tool permission map

Before every tool the agent uses, Bill checks that you are allowed. Each tool needs one key: reading and searching needs agent.ask; comments on Azure DevOps items need ado.comment; changing work items needs ado.write; branches, pipelines and pushes need code.push; sandbox work needs target.sandbox.use; device work needs target.device.use; allow-listed server scripts need target.server.run_script. A tool that is not listed counts as a write and needs agent.command. Writes asked in chat or voice may need an approval card first.

Caching and failure

Answers are remembered briefly (allows for at most 15 seconds, denies for at most 5), and a role change takes effect straight away. If the check cannot answer in time or answers badly, the request is refused with reason pdp_unavailable and nothing is remembered. Try again shortly, and tell your Bill and Ben contact if it keeps happening.

All permission keys

Change the catalogue, then regenerate this table; never edit it alone.

Console pages

Key	On	What it allows	Assurance	Plan gate	Class
console.section.users.view	tenant	see the users console page	strong	-	read
console.section.roles.view	tenant	see the roles console page	strong	-	read
console.section.agents.view	tenant	see the agents console page	strong	-	read
console.section.channels.view	tenant	see the channels console page	strong	-	read
console.section.usage.view	tenant	see the usage console page	strong	-	read
console.section.billing.view	tenant	see the billing console page	strong	-	read
console.section.audit.view	tenant	see the audit console page	strong	-	read
console.section.privacy.view	tenant	see the privacy console page	strong	-	read
console.section.devices.view	tenant	see the devices console page	strong	-	read
console.section.knowledge.view	tenant	see the knowledge console page	strong	-	read
console.section.gateway.view	tenant	see the gateway console page	strong	-	read

Agents

Key	On	What it allows	Assurance	Plan gate	Class
agent.ask	binding	the agent answers a question (read-only tools); a tenant may opt in to weak assurance	linked	-	read
agent.command	binding	the agent takes a task, uses write tools, joins work	linked	-	write
agent.configure	agent	change instructions, skills, tools and the unauthorised policy (creating custom agents is gated by the custom_agents entitlement, checked by the console)	strong	-	admin
agent.pause	agent	pause or resume an agent	strong	-	admin

Meetings

Key	On	What it allows	Assurance	Plan gate	Class
meeting.invite_agent	binding	send the agent into a meeting	linked	entitlement:meeting_minutes	write
meeting.voice_command	binding	spoken commands are accepted	linked	-	write

Channels

Key	On	What it allows	Assurance	Plan gate	Class
channel.bind_agent	channel	enable an agent in a chat, channel or meeting series	strong	-	admin

Helmora

Key	On	What it allows	Assurance	Plan gate	Class
canvas.board.list	tenant	list the boards you can open	strong	-	read
canvas.board.create	tenant	create a board	strong	-	write
canvas.board.view	board	view a board	strong	-	read
canvas.board.edit	board	edit a board	strong	-	write
canvas.board.manage_members	board	manage who can use a board	strong	-	admin
canvas.plan.execute	board	press Execute on a plan	strong	-	write
canvas.node.approve	plan_run	approve a gated node (still needs the node's own target permission)	strong	-	write

Execution targets

Key	On	What it allows	Assurance	Plan gate	Class
target.sandbox.use	target	run work in the sandbox	linked	entitlement:sandbox_minutes	write
target.device.use	device	run on this device (owner by default; sharing = tuples)	strong	business	write
target.device.enrol	tenant	enrol own device	strong	business	write
target.server.run_script	target	allow-listed ops scripts	strong	entitlement:server_scripts	write

Code

Key	On	What it allows	Assurance	Plan gate	Class
code.push	tenant	Ben pushes branches or pull requests	linked	-	write

Azure DevOps

Key	On	What it allows	Assurance	Plan gate	Class
ado.write	ado_project	change Azure DevOps work items	linked	-	write
ado.comment	ado_project	comment on Azure DevOps items	linked	-	write

Gateway

Key	On	What it allows	Assurance	Plan gate	Class
gateway.connect	tenant	connect an external AI client to the gateway	strong	entitlement:gateway	write
gateway.tool.*	tool	use one gateway tool, e.g. gateway.tool.	strong	entitlement:gateway	write
gateway.detail.full	tenant	gateway answers in full detail instead of summary mode	strong	business	read

Knowledge

Key	On	What it allows	Assurance	Plan gate	Class
knowledge.search	collection	search a knowledge collection	linked	business	read
knowledge.manage	collection	manage a knowledge collection	strong	business	admin
knowledge.admin	tenant	run the library: create and list collections, search model and ranking settings (owner and admin through knowledge.*)	strong	business	admin

Model roles

Key	On	What it allows	Assurance	Plan gate	Class
model.role.*	tenant	use a model role alias, e.g. the deeper-reasoning model	none	entitlement:model_roles	read

Administration

Key	On	What it allows	Assurance	Plan gate	Class
admin.users.manage	tenant	administer users	strong	-	admin
admin.roles.manage	tenant	administer roles	strong	-	admin
admin.identity.manage	tenant	administer identity providers (SSO/SCIM need the Business plan, checked by the console)	strong	-	admin
admin.agents.manage	tenant	administer agents	strong	-	admin
admin.channels.manage	tenant	administer channels	strong	-	admin
admin.models.manage	tenant	edit the tenant model allow-list (which model vendors the tenant's agents may use)	strong	-	admin
admin.meeting_logins.manage	tenant	register the tenant's own meeting bot accounts (Attendee login group)	strong	business	admin
admin.entra.connect	tenant	start the Microsoft 365 admin consent that links the tenant's Entra tid	strong	-	admin
admin.teams_package.download	tenant	download the Teams app package for a custom upload (the store listing is the normal route)	strong	-	admin

Audit

Key	On	What it allows	Assurance	Plan gate	Class
audit.view	tenant	read the audit log	strong	-	read
audit.export	tenant	export the audit log	strong	business	read

Privacy

Key	On	What it allows	Assurance	Plan gate	Class
privacy.export	tenant	GDPR export	strong	-	read
privacy.delete	tenant	GDPR delete	strong	-	admin
privacy.retention.manage	tenant	set retention periods	strong	-	admin

Billing

Key	On	What it allows	Assurance	Plan gate	Class
billing.view	tenant	see invoices and plan	strong	-	read
billing.manage	tenant	change plan and spend cap	strong	-	admin

Usage

Key	On	What it allows	Assurance	Plan gate	Class
usage.view	tenant	see usage	strong	-	read
usage.view_own	tenant	see your own usage	strong	-	read