> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.astropods.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server. # Access control Resources are private. Deployments, private blueprints, and knowledge stores are reachable only by people who have been given access to them. Belonging to the organization grants nothing on its own, and there is no setting that restores blanket access for all members. This page explains the model. To put it to work, see [Manage access with groups](/access-groups). ## Where access comes from Three sources feed into one decision, and a person gets the sum of all three. | Source | What it grants | | -------------------- | ---------------------------------------------------------------------------------------------------------------- | | Account role | An account administrator reaches every resource in the account. An account member reaches nothing automatically. | | Direct resource role | A role you grant to one person on one deployment, blueprint, or knowledge store. | | Group role | The same, granted to a [group](/access-groups) so everyone in it inherits the role. | Access is a union, so the most permissive source wins. Adding a grant never takes access away. An account member is not locked out of the product. Members create resources, and the creator becomes the Admin of whatever they create. What a member does not get is access to resources somebody else made. ## 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. | Permission | Covers | | --------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `read` | Discover and read the resource: detail, configuration metadata, logs, traces, monitoring, and files. Secret values stay redacted. | | `edit` | Change the resource's content or metadata. | | `operate` | Redeploy, roll back, restart, stop, resume, cancel, and trigger ingestion. | | `manage_access` | Grant and revoke access to the resource. | | `delete` | Delete the resource. | 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. | Role | Deployment | Blueprint | Knowledge store | | ------ | ------------------------------------- | ------------------------------------------------- | ------------------------------------- | | Viewer | `read` | `read`, including use as a deployment source | `read` | | Editor | Viewer plus `edit`, `operate` | Viewer plus `edit`, `operate` | Viewer plus `edit`, `operate` | | Admin | Editor plus `manage_access`, `delete` | Editor plus `manage_access`, `delete`, `transfer` | Editor plus `manage_access`, `delete` | 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. ## 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 | Who gets in | | ------------------------- | -------------------------------------------------------------------------- | | Anyone | Any signed-in Astropods user. On Slack, anyone in the connected workspace. | | An organization | Every current member of that organization. | | A person | That one person. | | An [audience](/audiences) | Everyone currently on the list. | Grant an interface access from the agent's **Configure** screen. Granting the web interface does not grant Slack. > **Note** > > An agent whose interface has no entries at all falls back to letting members of the owning account in. Adding any entry to that interface turns the fallback off, so the list becomes the only way in. ## 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, so a deployment a teammate created and never shared does not appear in your deployment list at all. 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. | Response | Meaning | What to do | | -------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `404` | You lack access to that resource, or it does not exist. | Ask for `read` on it. The two cases are deliberately indistinguishable. | | `403` | You reached an account-level action your account role does not allow. | Ask an account administrator. | | `503` | The authorization service could not be reached. | Retry. This is not a denial. | A resource-level denial 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. `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: | | | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Other organizations | The member still works in this organization, and in any other organization they belong to. | | Their own agents | Nothing is deleted, and no agent is moved. A stopped agent keeps its history and its settings. | | Who it reaches | Members of the organization. Somebody who never joined it is not covered, because nothing connects that account to the organization. | 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](/access-groups): grant these roles to a team at once * [Audiences](/audiences): keep one list of people and grant several agents access to it * [Working with accounts](/accounts): account roles and switching between accounts * [Manually authorize requests](/manual-authz): run these same checks yourself from an agent