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#

Every provider in config/providers.php is offered in account settings. Since 2.114.81, the per-provider *_ENABLED installation switches no longer exist; setting an old key does not hide that provider. A usable credential is still required for cloud inference, and account permissions, model restrictions and quotas still apply. Offering a connection does not prove that the provider accepts the person's account or subscription.

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, with one narrow exception: a Pentest assessment can run on the model key from your account (inference_credential: account). ShvIA then hands your own key to the computer authorized to run that assessment, once per start and once per resume. It is the key you pasted for that model's provider, never an administrator-assigned key or a subscription token. With inference_credential: local, no key leaves ShvIA and the computer uses the credentials already on it. The account option is on by default; the operator can switch it off with PENTEST_ACCOUNT_KEY_ENABLED=false. Which one an assessment gets depends on where it is created:

• The Pentest page offers the choice only for a model whose provider you pasted a key for, on that provider's standard endpoint, and only when the Desktop and Pentest on that computer can ask for it. When it is offered, SHVIA account is already selected, and the page remembers no earlier pick, so each visit starts there; choose This computer to keep your key where it is. When the choice is not offered, the form sends none and the assessment uses the credentials already on the computer.
• A request to POST /pentest/authorizations or /pentest/authorizations/quick (a signed-in session, not an API key) means local when it leaves inference_credential out. Only account hands the key over, and an account request that ShvIA cannot honor is refused with 422 and creates no assessment.

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:

1. a key you pasted;
2. a subscription you connected;
3. a key an administrator assigned to you;
4. 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#

Three providers expose device login in this implementation: ChatGPT, OpenCode and xAI SuperGrok. ShvIA shows an address and a code, you approve the request with the provider, and the app finishes the connection. ShvIA stores and renews the tokens. This is separate from the API-key cards and from the native Code engine logins. Subscription traffic has no per-token price table here; an unknown cost is not a claim that usage is free or unlimited.

The Z.ai and Kimi Coding plans use pasted membership keys, not device login. Their separate provider ids preserve credential, endpoint and accounting boundaries. Z.ai's two providers also retain the account's Code-mode opt-in. These descriptions reflect the configured connection paths; this documentation review did not verify login, inference, renewal or plan eligibility with real subscription accounts.

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.

Recipe: MiniMax#

MiniMax is a cloud provider, so its models answer only for an account that holds a MiniMax credential (yours, or one an administrator assigned). Its models are called like any other, with the id from your list. The ids that exist are MiniMax-M3, MiniMax-M2.7, MiniMax-M2.5, MiniMax-M2, the faster -highspeed variants of some of them (which cost twice as much per token), MiniMax-M3.1-Flash and MiniMax-M3.1-Flash-Preview.

curl -s "$SHVIA_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash@minimax",
    "reasoning_effort": "low",
    "messages": [{ "role": "user", "content": "Summarise the deadline rules in two sentences." }]
  }'

Things that are specific to MiniMax:

• Two kinds of credential, and they are not interchangeable. A pay-as-you-go API key and the Subscription Key of the Token Plan are different credentials, and pasting the wrong one fails the call without saying why. Paste the one your plan gives you.
• MiniMax-M3.1-Flash takes reasoning_effort, and is slow without it. It always reasons, and with no reasoning_effort MiniMax runs it at max, its deepest level. Send low, medium, high, xhigh or max; the gateway passes the field on for this model. M3 and the M2 line do not take the field, so the gateway leaves it out for them. M3.1 Flash works with either kind of key and is in MiniMax's own GET /v1/models.
• MiniMax-M3.1-Flash-Preview needs the Token Plan key. MiniMax serves it only to a Token Plan or MiniMax Code credential for now, and refuses a pay-as-you-go key. The key of the plan starts with sk-cp-, and the model is offered in the list of an account whose MiniMax key starts that way. GET /v1/models of MiniMax itself does not list it, so it is not found by discovery alone: after you paste the key, call POST /api/v1/profiles/refresh and read the id from your list.
• The answer starts with <think>…</think>. MiniMax models write their reasoning into content and the gateway does not remove it. See chat completions for how to strip it.
• The data goes to China. The data_locality of MiniMax is cloud_cn, and an account with LGPD protection on is refused a call that names a collection and ends on this provider.

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. A reply without stream carries X-Inference-Fallback when another model answered, and the request header X-Inference-Strict: 1 turns the fallback into an error. 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.