Concepts
Tokens and scoping
API tokens carry granular permissions and optional folder scoping.
API tokens authenticate both the REST API and the MCP server. Create them on the Tokens page; each token starts with orca_ and is bound to the workspace you were viewing when you created it.
The full value appears once, at creation. Orcha stores only a hashed verifier afterwards, so a lost token cannot be recovered and has to be replaced. MCP clients that support OAuth can skip tokens entirely and authorize through a consent screen instead; see the MCP reference.
Permissions
| Permission | Allows |
|---|---|
read | Listing and reading files, folders, databases, and search |
write | Creating and updating files, folders, databases, records, and ingestion |
delete | Moving files, folders, databases, and records to trash |
Grant only what the agent needs. A research agent that only retrieves context needs read alone.
Scope
| Scope type | Behavior |
|---|---|
all | Token can access all folders and files in the workspace |
folders | Token is restricted to specified folders and their subfolders |
When a token is folder-scoped:
- Only files within the allowed folders are accessible; subfolders are automatically included.
- Root-level files (files with no folder) are excluded.
- Root-level databases are excluded; a database assigned to an allowed folder remains accessible.
- Folder-scoped tokens cannot write out-of-scope file references into database records, and inaccessible references are redacted from responses.
list_source_documentsand other source-level tools require a workspace-wide token.- Accessing an out-of-scope resource returns
403 Forbidden.