Provider Keys (BYOK)

Tracore lets you bring your own API key for any of four supported providers. Keys live on your user account globally — paste once, reuse across every workspace you own. An environment without a key assignment silently uses Tracore’s system Mistral as a fallback.

Supported providers

Each provider also exposes a small allowlist of additional models — see Choosing a model for the trade-offs.

Add a key

1. Open /profile in the Tracore web app.
2. Pick a provider card (one per supported vendor).
3. Click Connect, paste the API key from your provider’s console, and pick a default model.
4. Click Test & Save.

The save is atomic: Tracore calls the provider’s GET /models endpoint with your plaintext key first. On success the key is encrypted with AES-256-GCM and stored. On failure (400 invalid_key), nothing is persisted — your previously stored key (if any) is left untouched.

Rotate a key

On a connected card, click Replace. The flow is identical to the Connect form: paste the new key and Save. The previous ciphertext is overwritten only if the new key passes its provider test. In-flight extraction runs are unaffected — every run snapshots its { provider, model, apiKey } at enqueue time.

Remove a key

Click Remove on a connected card. The confirmation dialog enumerates every <workspace>/<env> tuple currently using the key. Confirming removes the row and cascades to those environments — their providerKeyId and model are nulled, so they revert to the system Mistral fallback automatically.

Default model

Each stored key has a defaultModel — the model preselected when you assign the key to an environment. You can change it without re-pasting the key:

• On the connected card, pick a different model from the Default model dropdown.
• Tracore submits a defaultModel-only update — no encryption, no provider call.

Per-environment overrides win over the profile default. See Environments for assigning a key + per-env model.

Test a key

The Test button on a connected card calls the provider’s GET /models endpoint with your stored key and updates the badge:

• Connected — last test succeeded.
• Invalid — last test returned 401/403. Rotate or remove the key.
• Not tested — no recent successful test.

Test calls are rate limited (10/min/user, 100/hr/user). On /profile page load, Tracore automatically re-tests any key whose last successful test is older than 7 days — the badge briefly shows a spinner during the check.

API surface

If you’d rather drive this from the SDK or raw API:

import { TracoreClient } from "@tracore/sdk";

const client = new TracoreClient({ apiKey: process.env.TRACORE_API_KEY! });

// List
const { data: keys } = await client.user.providerKeys.list();

// Connect or replace (atomic test+save)
await client.user.providerKeys.set({
  provider: "anthropic",
  key: "sk-ant-api03-…",
  defaultModel: "claude-haiku-4-5",
});

// Update default model only — no provider call
await client.user.providerKeys.set({
  provider: "anthropic",
  defaultModel: "claude-opus-4-7",
});

// Re-test
await client.user.providerKeys.test({ provider: "anthropic" });

// Remove
await client.user.providerKeys.remove({ provider: "anthropic" });