Api

Permission Model

Practical least-privilege patterns for Droplit API access.

Permission Model

Droplit supports Bitcoin-native request signatures and per-droplit API key allowlists. Use these controls together to model least-privilege access for production systems.

Core Control Layers

  1. Identity and key ownership: Sigma-hosted identity and signer flows manage user/application keys without exposing WIFs in your app.
  2. Request-level authorization: Every API request includes an X-Auth-Token signature tied to requestPath and request body.
  3. Droplit-level API key allowlists: Each droplit can explicitly permit or deny public keys at the faucet boundary.
  4. Operational configuration limits: Faucet settings (for example tap amount behavior) constrain what allowed keys can do.

Pattern A: Single backend service

  • Use one service public key in the droplit allowlist.
  • Sign each request path/body pair in backend code.
  • Restrict this key to one production service boundary.

Pattern B: Multi-agent runtime

  • Create one key per agent role (payments-agent, monitor-agent, sync-agent).
  • Add only required keys to each droplit allowlist.
  • Rotate keys independently when an agent changes ownership or risk profile.

Pattern C: Environment isolation

  • Use separate droplits and separate key sets for dev, staging, and prod.
  • Never reuse signing keys across environment tiers.
  • Validate signatures in each environment with environment-specific secrets and URLs.

Suggested Scope Matrix

Agent / ServiceTypical endpointsRecommended key policy
Payments agent/faucet/:name/tap, /faucet/:name/fundDedicated key, allowlisted only on payout droplits
Data attestation worker/faucet/:name/pushSeparate key, write-only role to data droplits
Mint pipeline/faucet/:name/mintIsolated mint key, narrow owner and rotation schedule
Monitor daemon/faucet/:name/status, /faucet/:name/activity-streamRead-focused key with explicit monitoring ownership

API Key Allowlist Workflow

  1. Open your droplit dashboard.
  2. Add approved public keys for each service or agent role.
  3. Label keys by runtime and owner (prod-payments-agent, staging-monitor).
  4. Remove stale keys immediately during role changes or incident response.

Verification Checklist

  • Every request includes X-Auth-Token.
  • The signed payload always matches the exact request body sent.
  • No private keys or WIFs are stored in frontend code.
  • API keys are scoped per droplit and reviewed on rotation schedule.
  • Agent/service keys are labeled and auditable.

On this page

Permission ModelCore Control LayersRecommended Access PatternsPattern A: Single backend servicePattern B: Multi-agent runtimePattern C: Environment isolationSuggested Scope MatrixAPI Key Allowlist WorkflowVerification ChecklistRelated References