> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Access & scopes

> Understand API-key scopes, resource access lists, and organization roles.

AutoSage authorizes requests in two layers: **API-key scopes** for application calls and **organization roles** for signed-in users. Resource access is also checked against the key's environment, tenant list, and knowledge-base list.

## API-key scopes

Scopes use the `resource:action` format. A request must have the required scope and be inside the key's allowed environment and resources.

| Scope                    | Allows                                                |
| ------------------------ | ----------------------------------------------------- |
| `tenants:read`           | List and inspect accessible tenants                   |
| `tenants:write`          | Create or update tenants                              |
| `tenants:delete`         | Delete tenants                                        |
| `knowledge_bases:read`   | List and inspect accessible knowledge bases           |
| `knowledge_bases:write`  | Create or update knowledge bases                      |
| `knowledge_bases:delete` | Delete knowledge bases                                |
| `documents:read`         | List, inspect, and download documents                 |
| `documents:write`        | Upload and reprocess documents                        |
| `documents:delete`       | Delete documents                                      |
| `agents:read`            | List agents and inspect run history                   |
| `agents:write`           | Create, configure, deploy, and schedule agents        |
| `agents:run`             | Run agents and stop active runs                       |
| `agents:delete`          | Archive agents                                        |
| `query:rag`              | Create chats, send messages, and run grounded queries |
| `admin:full`             | Satisfy every required API-key scope                  |

<Note>
  If you omit scopes when creating a key, AutoSage grants a default integration set for tenant, knowledge-base, and document read/write operations plus `query:rag`. Specify scopes explicitly when you need a narrower key.
</Note>

<Warning>
  `admin:full` is a scope wildcard, not a blanket resource-list bypass. When `tenant_ids` or `knowledge_base_ids` is populated, resolving a specific resource still enforces that allowlist. Tenant listing is the exception: an `admin:full` key can discover every tenant in its environment. Use this scope only for a trusted server-side provisioning key, never for a browser, mobile app, or customer-specific workload.
</Warning>

### Scopes and resource lists work together

A key with `documents:write` can upload only to knowledge bases it is allowed to reach. Conversely, listing a knowledge base on a key does not grant permission to write documents unless the key also has `documents:write`.

```
Request allowed = correct environment
               + allowed tenant / knowledge base
               + required scope
```

See [Tenancy](/developers/concepts/tenancy) for resource-list behavior and [Authentication](/developers/authentication) for creating and protecting keys.

## Organization roles

Signed-in users receive a role for each organization they belong to. Roles govern dashboard and administrative operations; endpoint-specific checks still apply.

| Role            | Typical capabilities                                                                                      |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `owner`         | Full organization access, including members, roles, billing, environments, tenants, content, and deletion |
| `billing_admin` | Billing and day-to-day administration of environments, tenants, knowledge bases, and resources            |
| `developer`     | Create and edit permitted content such as documents and chats without organization-level administration   |
| `viewer`        | Read-only access to organization resources                                                                |

<Info>
  Owners have full access within their organization. Organization membership and role checks apply to user sessions; API keys use scopes and resource access lists instead.
</Info>

## Recommended key split

For most production integrations, keep the number of keys small and give each one a clear responsibility:

<CardGroup cols={2}>
  <Card title="Provisioning key" icon="gears">
    A tightly protected backend key with tenant and knowledge-base write scopes. Add `admin:full` only when broad scope coverage is truly required; populated resource allowlists still apply.
  </Card>

  <Card title="Runtime key" icon="comments">
    A backend key with `query:rag` and read access to only the resources used by the application.
  </Card>
</CardGroup>

<Tip>
  Start with the minimum scopes and resource lists a workload needs. Add a permission only when a specific operation requires it, and rotate keys on a regular schedule.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="API keys" icon="key" href="/developers/api/api-keys">
    Create, inspect, and revoke keys.
  </Card>

  <Card title="Integration best practices" icon="list-check" href="/developers/guides/best-practices">
    Apply security, tenancy, reliability, and cost guidance together.
  </Card>
</CardGroup>