Authentication & API Keys — Developer Docs
Bearer pd_live keys, where to create them, scopes, and key-handling rules.
How do I authenticate REST requests?
Every REST request sends an organization API key as a Bearer token:
Authorization: Bearer pd_live_...Create keys in Account -> API keys. Organization owners and active members can create keys; owner-created keys are org-wide, while member-created keys only authorize projects the member owns or is explicitly shared into. A connector (OAuth) session is always scoped to one person: it sees only projects that user owns or is shared into, whatever their role.
Key facts:
- Keys are shown once at creation. Copy the full
pd_live_secret while it is visible — only a hashed form is stored. - Keys can carry an optional expiry and optional daily/monthly credit caps.
- Rotate or revoke keys anytime from Account -> API keys.
- Test a key with
GET https://api.precisiondocs.ai/v1/wallet.
What scopes do API keys have?
Each key carries a scope list. Requests to an endpoint outside the key's scopes fail with 403 insufficient_scope.
| Scope | Grants | Default |
|---|---|---|
project:create | Create projects (POST /v1/projects) and run plan checks (POST /v1/plan-check) | Yes |
project:read | List/poll projects, site knowledge, messages, reports, search | Yes |
agent:ask | Ask the project agent (POST /v1/projects/{id}/messages) | Yes |
report:write | Generate reports (POST /v1/projects/{id}/reports) | Yes |
source:write | Add URL and GIS sources and upload files (POST .../sources, POST .../gis-sources, POST /v1/uploads/*) | Yes |
artifact:read | List artifacts and mint signed download URLs | Yes |
wallet:read | Read the organization credit balance | Yes |
gis:export | GIS export artifacts (POST .../gis-exports) and map/aerial rendering (POST .../maps) | Yes |
siteplan:read | Site Plan Studio design data: concept geometry, design criteria, yield scenarios, CAD exports | Yes |
There is no custom-scope picker: every new key carries the full set above, and a connector (OAuth) token carries the same set.
Security rules:
- Never paste a
pd_live_key into a shared document, prompt, chat message, screenshot, or support ticket. - Put keys only in server-side config or the local MCP
env.PRECISIONDOCS_API_KEYfield. - Rotate a key immediately if it may have been exposed.