Permissions and secrets

When an action is refused, or an agent cannot reach a secret or a file it needs, this is a permissions question, and the fix is a grant or a binding rather than a workaround. Disco Parrot checks every action against the scopes the person holds, and it keeps secrets in a vault that hands a credential to a run only as a short-lived lease. So a refusal is the platform doing its job, and clearing it is a matter of granting the right role or wiring the credential the right way. This page covers the three you will meet.

A "permission denied" message

What you see. An action is refused with a permission message that names the scope it needed, for example a message that you are missing the audit.export scope.

Why it happens. Every action maps to a scope, and you can only take an action your roles grant the scope for. A denial means one of two things, and the message tells you which. Either your roles do not include the scope, or the scope is one of a few that your plan has to include as an entitlement and your plan does not. The first is a role question; the second is a plan question, and the message names a missing entitlement rather than a missing scope.

How to fix it. For a missing scope, an admin grants you a role that includes it. The fastest path is to read the scope from the message, find a built-in role that carries it in the scope catalog, and have an admin assign that role on the members page; a custom role works too when no built-in is a clean fit. For a missing entitlement, the fix is the plan, not the role: the scope stays inert until the workspace is on a plan that includes the entitlement, so an admin or billing owner moves the workspace to a plan that carries it. The handful of entitlement-gated scopes are called out in the plans and entitlements reference.

The agent cannot reach a secret

What you see. A run cannot complete an action that needs a credential, a token to reach an external service, for example, and the step reports it could not get the credential rather than reporting the secret value.

Why it happens. Secrets live in a write-only vault: the platform stores a secret and uses it on your behalf, but it never shows the value back, not to a user and not to an admin. A run does not hold standing credentials; when a step genuinely needs one, it requests a short-lived lease for that one operation, and the credential is delivered to a single process and cleaned up after. An agent cannot reach a credential when there is no lease path configured for it: the work needs a capability the sandbox profile does not bind, the binding points at a secret that is not in the vault, or the person the run acts for is missing the scope the binding requires. The platform also refuses a managed secret that is set as a standing environment value on a sandbox, on purpose, so a credential is never quietly baked into a container.

How to fix it. Configure the credential to be leased, rather than handing the agent the secret. An admin opens the sandbox profile and adds a capability binding for the operation, points it at the secret's name in the vault, and lists the scope it requires; if the secret is not in the vault yet, an admin adds it there first. If the binding exists but the run still cannot get the credential, the person the run acts for is missing the scope the binding names, which an admin grants the same way as any other scope. The deep version of how a credential reaches a run, leased for one operation and never persisted, is on credential leases.

The agent cannot reach a file

What you see. A run cannot find or open a file you expected it to work on, or it reports the file is outside what it can reach.

Why it happens. An agent works inside its own sandbox against a fresh clone of your repository, and what it can reach is what the sandbox profile gave it. A file is out of reach when the repository it lives in is not one the profile mounts, so it was never cloned into the sandbox, or when a path points outside the workspace the sandbox is allowed to read. The boundary is deliberate: a run reaches the repositories its profile names and nothing else, which is what keeps one run from reading another's work or the host underneath it.

How to fix it. Read which case you are in, and the fix follows from it.

• The repository is not on the profile. Add it to the sandbox profile so it is cloned into the sandbox, then run again.
• The repository is mounted, but the path is wrong. A file is reached relative to where its repository is mounted in the workspace. Point the work at the path under the mounted repository, not an absolute path on the host; a path that climbs outside the workspace is refused by design.
• The repository was not cloned because a connection lapsed. That is a connection fix. Reauthorize the repository on connections and access, then run again.

How scopes, roles, and entitlements fit

Three things decide whether an action goes through, and a denial is always one of them. A scope is the permission for a single action. A role is a named set of scopes that an admin grants to a person; this is how almost every permission is given. An entitlement is a capability your plan includes, and a few scopes stay inert until the plan carries the matching entitlement. So when something is refused, the question is which of the three is missing: a role grant for a plain scope, or a plan that includes the entitlement for a gated one. The message tells you which, and the fix follows from it.

Clearing a denied action, start to finish

A teammate tries to export the audit log and the action is refused. The message is specific: it names the audit.export scope and says an administrator can grant a role that includes it. She does not look for a setting to toggle or a way around the check.

She copies the scope from the message and opens the scope catalog. It shows audit.export is carried by a compliance-minded role, and that the scope is one of the few gated by an entitlement, so she checks the workspace is on a plan that includes it. It is, so a role grant is the whole fix. She sends the admin one line: the action she was refused and the scope it named.

The admin opens the members page, assigns her the role, and the grant is recorded against his name. She retries the export and it goes through. The grant is on the books for anyone who looks later.

One message, one scope, one role grant. Nothing was worked around, and the grant is on the record.

Still refused after a grant

If an admin granted the role and the action is still refused, read the message once more, since it names the current cause and a second scope may be missing for the same action. Check too that the scope is not one your plan gates as an entitlement, which a role grant cannot clear on its own; the plans and entitlements reference lists the gated handful. If the message still names a scope a granted role should carry, quote that scope and the role you were given so anyone looking with you lands on the same place. Your account contact can pick it up from the scope the message names and the role on your account.

Why access is granted, not worked around

Every fix on this page is a grant or a binding rather than a way around the check, and that is the point. The platform refuses an action you do not hold the scope for, and it refuses to show a secret value to anyone, because the alternative, an action that runs without the permission or a credential that gets pasted where it can leak, is exactly what a team adopting agents needs the platform to prevent. So the path back is to grant the role, set the binding, or mount the repository, each of which leaves a record and each of which an admin can reason about. Access you restore this way is access you can account for later.

For a current user, the move is to read what the message named and take it to an admin: the scope to grant, the capability to bind, or the repository to mount. The message is specific so the ask can be specific.

For an administrator, these are the three levers you hold. A role grant clears a scope denial, a capability binding gives a run a credential without exposing it, and a profile's repository list decides what a run can read. Each is a deliberate grant, and each is auditable.

For a prospect, the takeaway is that access is governed, not improvised. An agent gets exactly the permissions and credentials it was granted, secret values are never shown to anyone, and restoring access is an explicit, recorded grant rather than a workaround.