Credentials System Deep Dive

How credential resolution works — three-tier hierarchy, Secure Vault, BYOK, and API cost tracking.

Written By pvdyck

Last updated 41 minutes 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 inside the Cloudflare Worker
  • Supports API key, OAuth 2.0, and Basic auth
  • OAuth tokens are refreshed automatically by Secure Vault

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

When a Builder pre-configures cost-bearing credentials (e.g., AI/LLM services) with an API Cost Multiplier, the system:

  • Records the actual API cost for each call
  • 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 do not show the multiplier option.

Credential Isolation

Credentials are scoped per service contract address and token ID. 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.

Related