Credentials

Crafted AI separates several credential surfaces. They are related, but they serve different paths:

• Provider keys (BYOK) — your own OpenAI or Anthropic API keys, stored encrypted on our side and used to call the upstream provider.
• Gateway keys — cai_… tokens that your applications use to call the Crafted AI gateway. These authenticate requests, identify your organisation, and carry per-key rate limits.
• Integration credentials — optional credentials used by MCP servers or external integrations.
• Twilio credentials — Account SID, Auth Token, and WhatsApp sender used by the WhatsApp product.

You need at least one provider key and one gateway key for API traffic. WhatsApp also needs Twilio credentials and a default organisation model.

Provider keys (BYOK)

1. Open app.craftedai.co and navigate to Credentials → Provider keys.
2. Click Add OpenAI key or Add Anthropic key and paste the key.
3. The key is encrypted with the gateway’s MODEL_CONFIG_ENCRYPTION_KEY (AES-GCM) before it touches the database. We never return the value after it is stored.
4. Rotate by adding a replacement key, switching traffic via the model catalog, then deleting the old key.

You can have one provider key per provider per organisation. Multi-key fan-out (e.g. cost-shifting between two OpenAI accounts) is on the roadmap.

Gateway keys

Gateway keys are how your application authenticates to the Crafted AI gateway. Each key has:

• A cai_… value, shown exactly once at creation time.
• An optional requests-per-minute (RPM) cap — enforced via Redis counters on every request.
• An optional daily token cap — combined prompt + completion tokens, enforced on the same Redis counters.
• An optional external user ID — a free-text label that flows through to usage reporting so you can attribute calls to your end users.

Minting a key

1. Go to Credentials → Gateway keys.
2. Click New key, set an optional label, RPM, and daily token cap.
3. Copy the cai_… value immediately. We do not store it in plain text and cannot show it again.

Rotation

Rotate keys whenever a value may have leaked, or on a schedule that fits your security posture. The recommended flow is:

1. Mint a new gateway key with the same RPM and daily token caps.
2. Roll the new value out to your applications.
3. Watch the old key’s traffic drop to zero in app.craftedai.co/usage.
4. Delete the old key.

Tip

Keep gateway keys short-lived where you can. The cost of rotation is one config change; the cost of a leaked key is unbounded.

Rate-limit behaviour

When a gateway key hits its RPM or daily token cap, the gateway returns 429 rate_limit_exceeded in the standard OpenAI envelope:

{
  "error": {
    "message": "Rate limit exceeded for this gateway key.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Per-key rate limits fail closed if Redis is unreachable — a deliberate trade-off, because these caps protect against runaway provider spend. Auth endpoints (/auth/*) on the control panel use a different, fail-open limiter; the gateway never does.

Integration credentials

MCP integrations may reference a stored credential when the MCP server requires authentication. Keep these credentials scoped to the MCP server’s narrow job:

• Prefer read-only or least-privilege service accounts.
• Avoid sharing provider keys with MCP servers unless that MCP server truly needs direct provider access.
• Rotate when a server, vendor, or team member changes.
• Refresh the MCP tool catalog after changing endpoint or credential settings.

Coming soon

The MVP stores MCP credential references but does not yet include a full credential marketplace or managed secret-broker UI for every integration type.

Twilio credentials for WhatsApp

The WhatsApp product uses Twilio as the transport. For the MVP, customers bring their own Twilio account.

WhatsApp app configuration stores:

• twilioNumber — the sender, formatted as whatsapp:+15551234567.
• twilioAccountSid — encrypted before storage.
• twilioAuthToken — encrypted before storage.

Read paths return only masked Twilio credential values. Rotation requires supplying the Account SID and Auth Token together, because Twilio credentials are treated as a paired secret.

See WhatsApp for the full setup flow.

What’s next

BYOK fan-out, per-key model allowlists, team-scoped gateway keys, managed Twilio onboarding, and richer integration-secret management are all on the roadmap. Track them in the changelog.