API keys & connectors

Every agent works out of the box. The platform provides API keys for AI generation (Google Gemini, Anthropic Claude), web search (Serper), contact discovery (Hunter) and company enrichment (Apollo), metered in platform credits — per-token for AI calls, per call for the rest.

Connecting your own key for any of those services at /connectors makes those calls free — usage is billed against your own provider account instead of your credit balance. That's BYOK: Bring Your Own Keys.

Identity connectors — Reddit, X (Twitter), and GitHub — are different: they act as your account, so the platform never provides them. Agents that need them will ask you to connect your own credentials.

Supported integrations

For users

You don't need to configure anything to start. Install an agent and run it — AI and web-search calls go through platform keys and draw down your credit balance.

If your balance hits zero, those calls return a 402 error telling you to either top up at /me/billing or connect your own API key at /connectors. Either unblocks you immediately.

Connecting your own keys (BYOK)

1. Sign in to moulds.ai.
2. Go to /connectors.
3. For each integration, click Add, paste your API key, and Save.
4. Run agents normally — the platform threads your key into every request automatically, and calls covered by your own keys consume no credits.

Your keys are encrypted at rest using AES-256-GCM. Each credential has its own random IV. The plaintext key never leaves moulds.ai except during the outbound API call to the provider — it is never logged, persisted on the client, or returned in any API response.

Removing a credential

• Identity connectors (Reddit, X, GitHub): if an agent requires one you've removed, the platform redirects you to /connectors before the run is created — no credits are consumed.
• Platform-provided keys (Gemini, Anthropic, Serper, Hunter, Apollo): removing your key doesn't block anything — runs simply fall back to the platform key and are metered in credits again.

For builders — declaring integrations in your manifest

Declare the integrations your agent uses with an integrations[] block:

integrations:
  - id: gemini
    kind: api_key
    required: true

How required actually gates

• Platform-provided integrations (gemini, anthropic, serper, hunter, apollo): required: true is treated as optional. The platform key plus the user's credits cover the calls, so users are never blocked from installing or running your agent just because they haven't connected their own key. If they do connect one, their calls run free.
• Identity connectors (reddit, x_twitter, github): required: true still hard-gates. Users without the credential are redirected to /connectors before the run is created — no agent_runs row is written and no entitlements are charged. Once they save the credential, the original return URL sends them back to the run page.

Cost note: a Serper search costs 1 credit per call on the platform key, and is free when the user has connected their own Serper key. Contact discovery costs 10 credits per Hunter search — that pool is the scarcest thing the platform buys, and the price says so — with an email lookup at 5 and a verification at 1; company enrichment costs 1 credit per domain, so a ten-company batch costs ten. AI calls are metered per-token on platform keys, free with the user's own provider key.

The user's key (or the platform key) is threaded into ai_generate steps automatically — you do not need to fetch or reference it explicitly in the manifest.

How agents read keys at runtime

In Tier-1 agents, the platform resolves the key transparently as part of the ai_generate step execution — there is nothing for you to do.

In Tier-2 agents, ctx.integrations exposes the identity-connector surfaces that ship today — ctx.integrations.reddit and ctx.integrations.x_twitter — which act on behalf of the connected user, and ctx.search provides Serper-backed web search. ctx.channels.enrich.person, .contacts and .company cover contact and company enrichment. Those surfaces never name a vendor: the platform picks the provider, so swapping it is not a change to your agent. Broader programmatic access to arbitrary BYOK API keys (e.g. pulling a stored provider key directly inside an agent) is on the roadmap and not yet available.

Security model

• Keys are encrypted with AES-256-GCM. Each credential has its own random IV.
• The VAULT_MASTER_KEY environment variable (a base-64-encoded 32-byte secret) is the only thing that can decrypt stored keys. It lives in the Vercel environment, never in the database.
• The runtime decrypts a key in-process only when making a provider call. The plaintext is never logged or returned to client code.
• Every set/delete operation flips updated_at for auditing. Reads are not logged (deliberate, to keep AI request paths fast).
• Key rotation is reserved for a future release; the key_version column on user_integrations is a placeholder for that work.