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.
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.
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.
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.