Ragen AI Access Control: Roles, Keys, and Permissions

Ragen AI enforces permissions at two independent layers — what you can do in the application, and what documents the retrieval pipeline will surface in your answers. A document that you do not have permission to view will never appear in an answer, even when you query through the API directly. This is not a UI restriction; it is enforced inside the vector store on every search.

​

Two independent role systems

Ragen AI has two role systems that operate completely independently. Confusing them is the most common way to misread what someone can or cannot do. Someone can be an organization owner and have no platform role at all — that is the normal state for every customer account. Someone can be a platform administrator without belonging to the organization they are inspecting, which is what makes incident response and support possible.

​

Organization roles

Your organization role determines what you can see and manage within a single organization. admin and owner have identical day-to-day permissions. The only difference is that only the owner can dispose of the organization itself — transfer it to another owner or delete it entirely.

​

Platform role

The platform role (admin or user) controls access to the admin panel — a separate application used for cross-organization management. Platform admins can view usage across every organization, manage disk ceilings, revoke API keys, and access the activity log. Having a platform role does not grant membership in any organization and does not allow reading another organization’s documents through the main application.

​

Document permissions

Within an organization, individual files and folders carry their own visibility rules. Permissions are set at creation time based on ownership, and can be extended through explicit sharing. You can grant access at two levels:

• View — the document is included in retrieval results and the user can read its content
• Full access — the user can also edit, move, and delete the document

Folder permissions cascade automatically: granting access to a folder extends to all files and sub-folders inside it.

​

When a change reaches retrieval

The knowledge base list shows a sharing change at once. Retrieval follows a moment later. Each indexed passage stores who may read it, and a background job (syncDocumentAccess) rewrites that after every share, revoke or move, usually within seconds. Until the job runs, answers still use the previous access.

​

API key scope

Each API key is bound to one organization, and to a scope chosen when the key is created: one assistant, or the whole knowledge base. The key cannot cross its organization boundary — cross-organization requests are always rejected — and within the organization the scope is a boundary too: a request that disagrees with it is refused with 403 rather than obliged. The scope cannot be changed afterwards; issue a new key instead. Inside its scope, a key reads with the document permissions of the person who created it — the same filter the web app applies to them — so an agent using a member’s key never sees a file that member cannot open. See Whose permissions a key carries.

​

Debug mode

Each API key has an optional debug mode toggle, off by default. When enabled, every API request made with that key automatically saves the full conversation — user message and assistant response — as a thread in the API threads tab of the bound project. Use debug mode while building and testing integrations to inspect exactly what the API received and responded without adding logging to your own code. Disable it once your integration is stable — debug mode saves every conversation to the database and increases storage usage over time.