AI keys overview: bring your own key

SiteTrellis uses a bring-your-own-key (BYO key) model. You create an account with one or more AI providers, generate an API key, and add it to SiteTrellis. Your agent then calls the provider directly with your key whenever a visitor writes a message.

Why bring your own key#

• Transparent cost. The provider bills you at its own published rates. SiteTrellis adds no markup on AI usage. Plans limit conversations, agents, seats and features instead (see Billing and plans).
• Your choice of model. Use a small, fast, inexpensive model for simple support and a stronger one for complex questions.
• Your data agreements. Your relationship, and any enterprise or zero-retention terms, are directly with the provider.

The trade-off is that you are responsible for keeping credit available at the provider and for setting spending limits there.

Supported providers#

Adding a key#

1. Create the key at the provider (follow the guide for your provider).
2. In the SiteTrellis dashboard open AI providers and add a key. Choose the provider, give it a label that helps you remember its purpose (for example "Anthropic - production"), and paste the key.
3. SiteTrellis encrypts and saves it, then makes a small test request. The key's status becomes ok, or failing with the provider's error message.
4. In the agent builder, add the key to the agent's model chain and pick a model.

Keys belong to the account, so any agent in any workspace can use them. Anyone with the Admin or Owner role can manage keys; the Agent role cannot see them.

How keys are stored#

• Keys are encrypted at rest with libsodium (sodium_crypto_secretbox) using a server-side master key that is not stored in the database.
• After saving, only a short hint (the last few characters) is displayed. The full key is never sent back to your browser, never written to logs, and not included in exports.
• The key is decrypted in memory only for the instant it is needed to call the provider.

Testing and status#

Use the Test button next to a key to make a minimal request and update its status and last-tested time. A key shows one of three states: unverified (never tested), ok, or failing (with the last error). Test again after adding credit or changing limits at the provider. Failing keys are flagged in the dashboard.

Rotating and deleting keys#

• Rotate replaces the secret of an existing key entry with a new one. Agents that reference the entry keep working with no edits. Create the new key at the provider first, rotate, test, and only then revoke the old one at the provider.
• Delete removes the entry. The dashboard lists which agents use it. An agent whose chain step points at a deleted key cannot be published until you choose another key, and a published agent with a deleted key will fail over to its next step or its failure message.
• Rotate immediately if a key may have been exposed, and revoke it at the provider.

Costs and spend limits#

Costs depend on the model, the length of your system prompt and knowledge text, the history window, and how long replies are. Every request sends the prompt, your knowledge and the recent conversation, so large knowledge blocks multiply across every message. A few habits keep spending predictable:

• Set a monthly spend limit or budget at the provider. Each provider guide shows where. This is your hard safety net.
• Use a limited-purpose key. Create a separate key for SiteTrellis rather than reusing one that also powers other projects.
• Lower the history window and max tokens in the agent's model settings if replies are costlier than you need.
• Watch the numbers. The dashboard analytics show token usage and an estimated cost per agent and model. The provider's invoice is always authoritative.
• The agent-level setting limits.monthly_message_cap can stop an agent from answering after a number of messages per month (0 means no cap), and per-minute rate limits protect your key from abuse.

Fallback chains#

Each agent has an ordered model chain. Every step is a key, a model and some parameters (temperature, maximum reply length, timeout, retries). For each visitor message SiteTrellis tries step 1, and falls through to the next step when it hits:

• a network error or timeout,
• HTTP 429 (rate limited) or a 5xx/overloaded response,
• an invalid, expired or unauthorized key (the key is also marked as failing), or
• an empty or malformed response.

It does not fall through on a provider's content-policy refusal, because another model would usually refuse the same request, nor on a "bad request" error, which means the request itself is wrong and another provider would not fix it. Temporary errors are retried on the same step first (the step's retries setting), with a short backoff; timeouts are not retried. A step that keeps failing is skipped for a short while so visitors do not wait on a provider that is known to be down. The whole reply has an overall time budget of roughly half a minute (set by the platform, not per agent), so the sum of several slow steps is cut short. The conversation context is rebuilt for each step, so a mid-conversation switch to another provider keeps working, including tool-call history. If every step fails, the visitor sees the agent's friendly failure_message instead of a raw error.

The number of steps is limited by your plan (Free 2, Starter 3, Pro and Agency 5, at the time of writing). A strong pattern is to put a different provider in step 2 than in step 1, so a single provider outage does not take your chat down.

Which models can I choose?#

The dashboard offers models from a maintained list for each provider, together with whether they support tools (needed for custom HTTP tools, lead capture and escalation). Model names and prices change quickly, so this documentation does not list them. Pick from the model list in the dashboard, and check your provider's pricing page for current rates. If the provider releases a model that is not in the list yet, tell us through the contact page.

Data handling#

When a visitor chats, the message, the recent conversation, your prompt and your knowledge text are sent to the provider you selected. Read your provider's data usage and retention terms, and mention them in your privacy policy. See Security and privacy.