Docs · Guides
Providers and your own keys
Models come from two places. The operator runs some on its own servers, and these need nothing from you. The others are served by cloud providers, and for those you bring your own key (BYOK): the contract and the bill stay between you and the provider, and ShvIA forwards your calls.
Providers#
These providers are available as shipped. The operator can switch any of them off, and some need setup on the operator's side, so the list you see may be shorter.
| Provider | Credential | data_locality |
|---|---|---|
| Anthropic | your key | cloud_us |
| OpenAI | your key | cloud_us |
| xAI (Grok) | your key | cloud_us |
| Google Gemini | your key | cloud_us |
| Google Vertex AI | a service-account key | by region: cloud_br by default |
| Amazon Bedrock | your key | cloud_us, unless the operator declared another locality for it |
| Groq | your key | cloud_us |
| Together AI | your key | cloud_us |
| Novita AI | your key | cloud_us |
| OpenRouter | your key | cloud_us |
| Kilo Gateway | your key | cloud_us |
| IBM watsonx | your key | cloud_us |
| Mistral AI | your key | cloud_eu |
| Z.ai (GLM) | your key | cloud_cn |
| DeepSeek | your key | cloud_cn |
| Moonshot Kimi | your key | cloud_cn |
| MiniMax | your key | cloud_cn |
| OpenCode (Zen and Go) | your key, or a subscription login | cloud_us |
| ChatGPT (Go and Plus) | a subscription login only | cloud_us |
The last column is the data_locality that ShvIA assigns to the provider's models: the class of cloud they run in. The operator's own servers are on_prem. It is a label for you to apply your own policy to, not a statement about where the provider processes data. See your data.
Add your key#
Provider keys cannot be managed with an API key: use the web app. Open your account, go to the provider keys and paste the key for each provider. A request authenticated with an API key that tries to save or remove a provider key is refused with 403.
When you save a key, ShvIA asks the provider whether it works and tells you the result: accepted, refused, no credit, rate limited, or provider unavailable. The key is kept whatever the verdict, so that an outage at the provider is not read as a wrong key.
Your keys are encrypted at rest and are never returned by the API. configured_providers in GET /api/auth/me lists the providers for which you pasted a key. It does not list the ones you reach with a subscription login or with a key that an administrator assigned to you.
After you add a key, call POST /api/v1/profiles/refresh so that your model list is rebuilt from the provider with your key. Without it, the list is refreshed on its own every few minutes.
Where a credential can come from#
For one provider, the first of these that exists is used:
- a key you pasted;
- a subscription you connected;
- a key an administrator assigned to you;
- a key an administrator assigned to your whole group.
An administrator-assigned key may be limited to some models of the provider. A key you paste yourself is never limited this way, and it takes priority over an assigned one.
Subscription logins#
Two providers can be used with a subscription instead of a per-token key: ChatGPT (Go and Plus plans) and OpenCode. You connect them in the app with a device login: ShvIA shows an address and a code, you open the address in a browser and type the code, and the app finishes the connection. ShvIA stores and renews the tokens for you. The provider bills your subscription, so there is no price per token and usage shows no cost for these models.
GET /api/auth/me/provider-connections lists your connections and can be called with an API key. Connecting and disconnecting need a signed-in session.
Models with no key#
A cloud model can appear in GET /v1/models even when you have not added a key for its provider. What a call to it does then is easy to get wrong. The model cannot answer, and the gateway can fall back to your account's default model: the call succeeds with 200, and model and X-Inference-Model still name the model you asked for. It is possible to get an answer from a different model, with no error, without noticing. This holds for the /v1 endpoints, where the reply still names the model you asked for, and for agent/chat, whose reply names the model that answered. On the chat stream, the same call ends with an error event instead. See models.
GET /api/v1/profiles shows only the cloud models for which you hold a credential, so use it to see which cloud models you can call. It does not apply your group's list of allowed models or your quota, so a listed model can still be refused with 403. See models.
Cost#
For cloud models, the provider charges your account. ShvIA records tokens, and an estimate of the cost from a price table, so that you can follow your spend in usage and cost: where a provider reports the real cost, that is used instead. The price of a model is in price in GET /api/v1/profiles, in US dollars per million tokens.