Public API

DevSphere OS exposes a small, read-only public API secured by organization API keys. Today it provides read access to leads and invoices, with scoped keys, rate limiting, and request logging.

#Purpose

#Architecture

The public API lives under a versioned path (v1). Requests authenticate with an organization API key sent as a Bearer token. The key resolves the organization and its scopes; the endpoint checks the required scope before returning data.

Keys are created and managed by CEO/admin. The plaintext key (prefixed dvs_live_) is shown once at creation; only a SHA-256 hash is stored, so a lost key cannot be recovered — it must be rotated or revoked.

#How it works

#Reference

curl https://<your-app>/api/v1/leads \
  -H "Authorization: Bearer dvs_live_xxx.xxxxxxxx"

401 { "error": "invalid_api_key" }
403 { "error": "insufficient_scope", "need": "leads:read" }
429 { "error": "rate_limited" }

#Implementation notes

• Keys are per-organization, scoped, revocable, and rotatable; platform staff cannot read them (hash-only).
• Only GET leads and GET invoices are implemented today; other scopes exist for future expansion.
• last_used_at is updated on successful verification.

#Limitations

#Security considerations

#Best practices

• Store keys in a secrets manager.
• Handle 401/403/429 explicitly.
• Rotate keys periodically.

#Related documentation