Concepts
Tokens and scoping
API tokens have granular permissions and optional folder scoping.
API tokens authenticate the REST API and the MCP server. Create tokens on the API Tokens page. Each token starts with orca_. Each token is bound to the workspace that you view when you create it.
Orcha shows the full value one time, when you create the token. After that, Orcha stores only a hashed verifier. Thus, you cannot recover a lost token. You must replace it. MCP clients that support OAuth do not need tokens. They authorize through a consent screen. See the MCP reference.
Permissions
| Permission | Allows |
|---|---|
read | List and read files, folders, and databases, and search |
write | Create and update files, folders, databases, and records, and ingest content |
delete | Move files, folders, databases, and records to the trash |
Give only the permissions that the agent needs. A research agent that only retrieves context needs only read.
Scope
| Scope type | Behavior |
|---|---|
all | Token can access all folders and files in the workspace |
folders | Token can access only the specified folders and their subfolders |
When a token is folder-scoped:
- The token can access only files in the allowed folders. Subfolders are included automatically.
- Root-level files (files with no folder) are excluded.
- Root-level databases are excluded. A database in an allowed folder stays accessible.
- The token cannot write references to out-of-scope files into database records. Orcha redacts inaccessible references from responses.
list_source_documentsand other source-level tools need a workspace-wide token.- A request for an out-of-scope resource returns
403 Forbidden.