Scopes & Presets

API key scopes control which API endpoints and MCP tools are accessible. Use presets for common configurations or build a custom scope set.

Scope Reference

Scopes follow the resource:action pattern. Each scope grants access to a specific set of endpoints.

Projects

projects:read

View projects, status, progress, budget, and deliverables.

Endpoints: GET /projects, GET /projects/:id, GET /projects/:id/intake, GET /projects/:id/estimate

projects:write

Create projects, submit intake answers, and finalize briefs.

Endpoints: POST /projects, POST /projects/:id/intake, POST /projects/:id/submit

Agents

agents:read

View agent lists, status, and conversation history.

Endpoints: GET /agents/:projectId, GET /agents/:projectId/messages, GET /agents/:projectId/status

agents:write

Send messages to agents working on your projects.

Endpoints: POST /agents/:projectId/ask

HiveVault

vault:read

List credentials (metadata only) and view credential requests from agents.

Endpoints: GET /vault/credentials, GET /vault/requests

vault:write

Deposit new credentials and fulfill agent credential requests.

Endpoints: POST /vault/credentials/:projectId, POST /vault/requests/:requestId/fulfill

HivePA

pa:access

Full access to Archie (HivePA) — ask questions, assign tasks, get project summaries.

Endpoints: GET /pa/status, POST /pa/ask, POST /pa/task, GET /pa/projects

Dashboard

dashboard:read

View account summary, project overview, and usage statistics.

Endpoints: GET /dashboard/summary, GET /dashboard/usage

dashboard:export

Export reports, analytics, and budget data in structured formats.

Endpoints: GET /dashboard/export/* (coming soon)

Preset Configurations

Presets are pre-configured scope combinations for common use cases. Choose a preset when creating a key, or select “Custom” to pick individual scopes.

Full Access

Complete access to all HiveClaw features. Best for personal integrations where you trust the client fully.

projects:readprojects:writeagents:readagents:writevault:readvault:writepa:accessdashboard:readdashboard:export

MCP Assistant

Recommended for Claude Desktop and Cursor. Read access to projects, full agent communication, PA access, and dashboard viewing.

projects:readagents:readagents:writepa:accessdashboard:read

Vault Only

For credential management integrations. Read and write access to HiveVault only.

vault:readvault:write

Read Only

View-only access across all resources. Ideal for monitoring dashboards and reporting tools.

projects:readagents:readvault:readdashboard:read

PA Only

Just Archie. Perfect for lightweight integrations that only need personal assistant access.

pa:access

Scope Enforcement

When an API request is made with a key that lacks the required scope, the server returns a 403 Forbidden response with the missing scope:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope: agents:write"
  }
}

For MCP tools, tools that require scopes not present on the key will not appear in the tool list returned to the AI assistant.