Credentials System Deep Dive
How credential resolution works — three-tier hierarchy, Secure Vault, BYOK, and API cost tracking.
Written By pvdyck
Last updated 1 day ago
Credentials System Deep Dive
indie.money's credential system has three tiers. Understanding how they interact helps both Builders and Producers configure agents correctly.
Three-Tier Resolution Chain
When an agent runs, credentials are resolved in this order:
- Your own keys (Producer/BYOK) — When you provide your own API keys, those are used first. You control your API usage and rate limits directly.
- Builder-provided — Builder pre-configured credentials are used when you haven't provided your own.
- Platform-provided — indie.money provides built-in credentials for certain services. Fallback when the above are unavailable.
Secure Vault
All credentials are stored in the Secure Vault. Key properties:
- Encrypted at rest and in transit
- Decrypted only at execution time
- Supports API key, OAuth 2.0, and Basic auth
- OAuth tokens are refreshed automatically
BYOK (Bring Your Own Keys)
Producers who provide their own API keys are using BYOK mode. This is the most flexible option — you control your API usage and rate limits directly.
API Cost Tracking
Every provider has a cost model that determines how its API costs are tracked:
When a Builder pre-configures cost-bearing credentials (tracked, fixed, or variable) with an API Cost Multiplier, the system:
- Records the API cost for each call (actual from response, or declared from registry)
- Enforces the cost ceiling circuit breaker across all cost types
- Multiplies by the configured percentage
- Bills the resulting amount to the Producer
- Credits the difference (if markup > 100%) to the Builder
Free messaging APIs (Telegram, Slack, Discord) have no per-call cost and are not tracked.
Credential Isolation
Credentials are scoped per agent. A Producer's credentials for Agent A cannot be accessed by or mixed with Agent B — even if both agents use the same external service.
Security Audit Trail
All credential access is logged. Builders can see how often their pre-configured credentials are used (via execution count), but cannot see Producers' credential values.