Authentication

API keys

Keys look like dgs_live_… (160-bit entropy). The raw secret is shown exactly once at creation — only a hash is stored. Send it as a Bearer token:

Authorization: Bearer dgs_live_YOUR_KEY

Keys are organization-scoped: every resource you can read or write belongs to the key's organization. Ids from other organizations return 404 — never data. Revoked or expired keys return 401 immediately.

Scopes (least privilege)

Grant only what the integration needs:

• clients:read
• clients:write
• leads:read
• leads:write
• projects:read
• invoices:read
• proposals:read
• webhooks:manage

A missing scope returns 403 with the required scope named in the error.

Rate limits

120 requests per 60s, applied per organization and per key. Exceeding either returns 429. Back off and retry with jitter.

Errors, request IDs & idempotency

Errors are JSON: { "error": "…", "requestId": "…" }. Include the requestId when contacting support. POST endpoints accept an Idempotency-Key header — retrying with the same key replays the original response instead of duplicating the effect (7-day window, response carries Idempotency-Replayed: true).

Versioning

The API is versioned in the path (/api/v1). Backward-compatible changes (new fields, new endpoints) ship without a version bump — never rely on unknown-field rejection. Breaking changes get a new version with at least 6 months of parallel operation and deprecation notices in the changelog before v1 retires.