Credentials System Deep Dive
How credential resolution works — three-tier hierarchy, Secure Vault, BYOK, and API cost tracking.
Written By pvdyck
Last updated 18 days 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:
- Producer-provided (Tier 1) — Your API keys take priority. When you provide your own credentials, they override all other sources.
- Builder-provided (Tier 2) — Builder pre-configured credentials during publish. Used when you haven't provided your own.
- Platform-provided (Tier 3) — 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 (Tier 1) 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.