Use one shared API key for a connector (Tavily web search)
Most connectors call a third party as the user who started the session: Gmail or Linear, where each user signs in with their own account. Web search has no per-user account. The workspace stores one Tavily key, and every session uses it. This agent's connector runs as the deployment.
Demonstrates: connectors and their identity, serving and deploying an agent.
Run (after the setup below), from the example's folder:
MISTRAL_API_KEY=... uv run agents serve
The agent
from mistralai import agents
# Tavily authenticates with one bearer key held for the workspace, so there is no per-user grant to
# act on behalf of.
tavily = agents.connector("tavily", run_as="deployment", credentials_name="tavily-shared")
agent = agents.Agent(
model="mistral-large-4",
name="deployment-identity-agent",
description="Answers questions from the web using the workspace's shared Tavily key.",
instructions=(
"Answer questions by searching the web. Cite the URLs you used. Keep answers to a few sentences. "
"If a search returns nothing useful, say so instead of guessing."
),
connectors=[tavily],
)Connectors default to run_as="auto", which calls the third party as the session user.
run_as="deployment" uses a credential the workspace holds instead.
When the deployment identity is the right one
| The connector authenticates with | Identity to use |
|---|---|
| a key stored once for the workspace | run_as="deployment" |
| each user's own OAuth2 sign-in | "auto" (the default) |
A session running as the deployment has no user to ask, so it cannot start an OAuth2 sign-in. An
OAuth2 connector under run_as="deployment" fails unless the workspace already holds a credential
for it. To see how a connector authenticates:
curl -H "Authorization: Bearer $MISTRAL_API_KEY" \
https://api.mistral.ai/v1/connectors/tavily/authentication_methodsTavily returns "method_type": "bearer".
Set up the workspace key
The agent ships no Tavily key. Store yours once, as a Tavily connection shared with the workspace and
named tavily-shared, either in Mistral Studio or with the API.
In Mistral Studio, open the Tavily connector, add a connection named tavily-shared, paste your key and tick
Share these credentials with the whole workspace.
With the API:
curl -X POST -H "Authorization: Bearer $MISTRAL_API_KEY" \
-H "Content-Type: application/json" \
https://api.mistral.ai/v1/connectors/tavily/workspace/credentials \
-d '{"name": "tavily-shared", "credentials": {"bearer_token": "<your-tavily-api-key>"}}'credentials_name="tavily-shared" selects this connection by name, so the agent uses your key even
when the workspace has another Tavily connection set as its default.
Run it
From the example's folder, check what the CLI loads:
MISTRAL_API_KEY=... uv run agents infoIt lists the agent and its one connector:
Ask it one question in your terminal. agents chat runs the agent in your process:
MISTRAL_API_KEY=... uv run agents chat -m "Who won the 2026 Tour de France? Cite your source."The agent searches the web through the workspace's Tavily key, then answers with its sources:
Then serve it:
MISTRAL_API_KEY=... uv run agents serveor push the folder to a GitHub repository that the GitHub connector can read, and deploy it to Mistral (Deploy):
MISTRAL_API_KEY=... uv run agents deployNo hardening needed to deploy it
A hardened deployment accepts only the processes that serve it, through agents serve or agents deploy, registered with your key.
An agent whose connectors run as the session user acts on that user's behalf, so its deployment has
to be hardened: nobody else can then act for your users. agents deploy hardens such a deployment on its own.
Don't pass --no-hardened for it: its worker cannot register, and the deployment does not start.
This agent acts for nobody, so agents deploy leaves its deployment unhardened, with no flag.
Next steps
- Connectors: connectors, MCP servers and credentials.
- Deploy:
agents deployand its options.