Skip to main content
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.
ScopeAllows
tenants:readList and inspect accessible tenants
tenants:writeCreate or update tenants
tenants:deleteDelete tenants
knowledge_bases:readList and inspect accessible knowledge bases
knowledge_bases:writeCreate or update knowledge bases
knowledge_bases:deleteDelete knowledge bases
documents:readList, inspect, and download documents
documents:writeUpload and reprocess documents
documents:deleteDelete documents
agents:readList agents and inspect run history
agents:writeCreate, configure, deploy, and schedule agents
agents:runRun agents and stop active runs
agents:deleteArchive agents
query:ragCreate chats, send messages, and run grounded queries
admin:fullSatisfy every required API-key scope
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.
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.

​
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 for resource-list behavior and 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.
RoleTypical capabilities
ownerFull organization access, including members, roles, billing, environments, tenants, content, and deletion
billing_adminBilling and day-to-day administration of environments, tenants, knowledge bases, and resources
developerCreate and edit permitted content such as documents and chats without organization-level administration
viewerRead-only access to organization resources
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.
For most production integrations, keep the number of keys small and give each one a clear responsibility:

Provisioning key

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.

Runtime key

A backend key with query:rag and read access to only the resources used by the application.
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.

​
Next steps

API keys

Create, inspect, and revoke keys.

Integration best practices

Apply security, tenancy, reliability, and cost guidance together.