Access control

Deployments, private blueprints, and knowledge stores are reachable only through roles granted on them. Changing or sharing a resource always takes an explicit grant. In an organization account, every member also starts with read access to new resources through the Everyone in this org group, and an account administrator can turn that off.

This page explains the model. To put it to work, see Manage access with groups.

Where access comes from

Four sources feed into one decision, and a person gets the sum of all four.

Access is a union, so the most permissive source wins. Adding a grant never takes access away.

Members create resources, and the creator becomes the Admin of whatever they create. A member reaches a resource somebody else made only through a grant or, by default, through Everyone in this org.

Share with the whole organization

Every organization account has one Everyone in this org group. Its membership is every member of the account, and nobody manages it. When a member creates a deployment, blueprint, or knowledge store, the group receives Viewer on it. Members can find and read it, and cannot change it.

You can keep a resource private in two ways:

• One resource. Open the resource’s access section and remove the Everyone in this org row. This takes Admin on the resource, and the removal survives later syncs.
• Every new resource. Go to Settings, then Organization, then Security, and turn off Share new resources with “Everyone in this org” under Access. You need to be an account administrator to change it; other members can see it.

With the setting off, a new resource is visible only to its creator and to account administrators until someone shares it. The setting applies to resources created after you change it:

• Resources that already exist keep their current access.
• A resource created while the setting was off stays private if you turn it back on.
• To share one of those, grant the group a role on it like any other group.

A personal account has no group, because it has one member.

Permissions

A permission is a single action. Roles exist because permissions are tedious to hand out one at a time, but the permission is what actually gets checked.

Permissions do not imply one another. edit does not include read, and a role that looks higher on the ladder is higher only because it bundles more.

Roles

Each resource type uses the same three rungs, and each rung adds to the one below it.

Assign these roles from the resource’s own settings: the Settings tab of a private blueprint or a knowledge store, or Configuration > Access on a deployment. An audience keeps an Access button in its header, which opens beside the button on desktop and as a bottom sheet on mobile.

Admin is the rung that shares and the rung that destroys. Grant Editor to someone who should run a resource day to day, and keep Admin for the people who should be able to share or remove it.

A blueprint role and a deployment role are separate. A role on a blueprint grants nothing on the agents deployed from it, so a blueprint Admin who opens Configure on someone else’s deployment gets a 404. To configure or redeploy a deployment, you need Editor on that deployment. Ask its Admin or an account administrator to grant it.

With Viewer, a deployment’s Configuration opens read-only. General and Access show the settings without letting you change them, and Policies stays unavailable. Access lists only your own role, not the other people with access.

Who can talk to an agent

The roles above decide who can see and change a deployment. Who can use the deployed agent is a separate decision, made per interface: the web interface and Slack each carry their own access list, so the same agent can be open on one and restricted on the other.

A request is allowed only when it matches an entry on that interface’s list, and you can mix entry types.

Grant an interface access from the agent’s Configure screen. Granting the web interface does not grant Slack.

What appears in a list

A list shows only the resources you can read. This is the same check as opening one, applied to every row. In an organization account, Everyone in this org makes a new resource readable by every member, so it appears in everyone’s list. A resource kept private does not appear in your list at all, whether its creator removed the group’s row or the account has sharing off. It is not hidden behind a lock icon; it is absent.

Public blueprints are the exception and are always listed, whether or not you belong to the account that owns them.

If you expect to see something and don’t, you need read on it. Ask someone with Admin on that resource, or an account administrator, to grant it.

When access is denied

The response depends on what was denied.

A 403 refusal from your role or your account membership has this body:

{
  "error": "authorization denied",
  "code": "AUTHORIZATION_DENIED",
  "action": "deployment:operate",
  "details": "You need the Editor role on this deployment to control how it runs. Ask a deployment admin or an account admin for access."
}

details names the role that grants the action and who can give it. Its wording can change, so in a script, match the code field rather than the error text or the ast CLI’s output. The ast CLI prints details as the server wrote it, so it reads the same as the web console.

A resource you cannot see returns 404 rather than 403 on purpose. A 403 would confirm that the resource exists, which leaks the names of things you cannot see. The tradeoff is that a real typo and a real permission problem look identical, so check the identifier before assuming it is access. A resource you can see returns 403, because the refusal tells you nothing you don’t already know.

503 is worth handling separately in a script. It means the decision could not be made, not that the answer was no, so retrying is correct where retrying a 404 is not.

When a change takes effect

Access changes apply immediately. Nobody needs to sign out, and no token has to expire first: each request is authorized against current access.

The web console caches permission checks briefly, for about 30 seconds, and refreshes them when the window regains focus. So a button may stay grayed out for a few seconds after someone grants you a role. The underlying access is already live; reload if you don’t want to wait.

Buttons in the console are enabled only after the server confirms you hold the permission. That check is a convenience, not the enforcement: every action is authorized again when you actually take it.

Personal accounts

A personal account has one member, who is its administrator and reaches everything in it. There is nobody else to grant access to, so access panels do not appear. The model is unchanged, it just has nothing to decide.

Block deploys to personal accounts

An organization can require that its members keep their work inside an organization rather than in a personal account. Go to Settings, then Organization, then Security, and turn on Block deploys to personal accounts. You need to be an account administrator to change it; other members can see it.

While it is on, a member of that organization cannot:

• deploy, redeploy, or roll back an agent in any personal account, or start one they paused
• create a blueprint in one, or push a new build to a blueprint already there, from the CLI or from a connected GitHub repository
• transfer a blueprint into one

The refusal names the organization that refused and the policy behind it, and it applies wherever the member works: the dashboard, the CLI, the API, and GitHub. A refused GitHub build fails, and its notification carries the same reason.

Agents already running in a member’s personal account are stopped, and the member cannot start them again. Each one shows as Restricted with the reason.

What the setting does not change:

Turning the setting off lifts the refusal and starts the stopped agents again. So does removing the member from the organization.

Next steps

• Manage access with groups: grant these roles to a team at once
• Audiences: keep one list of people and grant several agents access to it
• Working with accounts: account roles and switching between accounts
• Manually authorize requests: run these same checks yourself from an agent