Providers and API Keys

This page shows how you roll out LLM, embedding, and transcription providers, how you handle their API keys, and how you describe models of your own. How AI Studio decides which provider may see which data is on Confidence and Data Security.

Rolling out providers

Your configuration lists providers in CONFIG["LLM_PROVIDERS"], CONFIG["EMBEDDING_PROVIDERS"], and CONFIG["TRANSCRIPTION_PROVIDERS"]. The example configuration plugin shows every field. The easiest way to get an entry is to set the provider up in AI Studio and export it, see Testing and Exporting Configurations.

A provider of a cloud service:

CONFIG["LLM_PROVIDERS"][#CONFIG["LLM_PROVIDERS"]+1] = {
    ["Id"] = "4f6b3a8e-2d4c-4b1a-9e5f-7a8b9c0d1e2f",
    ["InstanceName"] = "Mistral Large for everybody",
    ["UsedLLMProvider"] = "MISTRAL",
    ["Host"] = "NONE",
    ["Hostname"] = "",
    ["APIKey"] = "ENC:v2:<the encrypted key from your export>",
    ["AdditionalJsonApiParameters"] = "",
    ["Model"] = {
        ["Id"] = "mistral-large-latest",
        ["DisplayName"] = "Mistral Large",
    },
}

A self-hosted server sets UsedLLMProvider to SELF_HOSTED, names the server software in Host (LM_STUDIO, LLAMA_CPP, OLLAMA, VLLM, or LLMMAN; for transcription also WHISPER_CPP), and its address in Hostname.

Users see your providers with a lock and can't change them. Whether they may add providers of their own is up to you:

Setting	Effect
DataApp.AllowUserToAddProvider	false disables adding providers of any kind.
DataApp.AllowUserToAddLLMProvider, …AddEmbeddingProvider, …AddTranscriptionProvider	Fine-tune it per kind, as long as the setting above allows adding at all.
DataApp.PreselectedProvider	The provider that AI Studio selects by default everywhere.
DataApp.UseTranscriptionProvider	The transcription provider for voice input.

Your own icon for a provider

AI Studio shows the logo of the provider's company next to each provider. To show your own logo instead, for example, of a project or a department, add IconPath with the path of an SVG file inside your plugin folder:

    ["IconPath"] = "assets/project-icon.svg",

The path is relative to your plugin.lua and must stay inside the plugin folder. AI Studio rejects absolute paths, .., links that lead out of the folder, files larger than 32 KiB, and anything that isn't a well-formed SVG. A rejected icon isn't fatal: the provider keeps its built-in logo, and the log says why. The SVG must bring its own colors, which should work on light and dark backgrounds, and your organization needs the rights to it. IconPath works for all three kinds of providers.

Encrypted API keys

A configuration may contain API keys. So that they don't appear in plain text in your plugin, you encrypt them with a secret that you deploy to the devices.

This hides the keys, it doesn't make them secret. Users with administrator rights on their device can find the decrypted key with enough effort. Encryption protects against accidental exposure, for example, when you review or share a configuration, and against casual snooping. Treat every key you roll out as known to its users, and limit what it allows at the provider, for example, with a budget.

Setting it up

1. Create a secret. In "Settings" → "App Options", switch on "Show administration settings?". In the "Enterprise Administration" section, click "Generate an encryption secret and copy it to the clipboard". AI Studio creates a random 256-bit key and copies it as Base64 text.
2. Deploy the secret to every device, as config_encryption_secret in the registry, as the policy file config_encryption_secret.yaml, or as the environment variable MINDWORK_AI_STUDIO_ENTERPRISE_CONFIG_ENCRYPTION_SECRET, see the deployment page of your operating system. The secret can be deployed on its own, without any configuration. Deploy it to your own device as well.
3. Export the provider with its key. AI Studio asks whether to include the key, and writes it encrypted, as ENC:v2:… or ENC:v1:….
4. Paste the fragment into your configuration plugin.

The "Information" page shows whether a device has an encryption secret. When AI Studio loads the configuration, it decrypts the key and stores it in the credential store of the operating system: the Windows Credential Manager, the macOS keychain, or the Secret Service on Linux. The same works for the tokens and passwords of ERI data sources, and for the API keys of tools.

The two formats

Format	Starts with	Read by	A value encrypted with another secret
Protected	ENC:v2:	AI Studio v26.10.1 or newer	is always refused
Compatible	ENC:v1:	every version	is usually refused, but in rare cases decrypted into a wrong key

AI Studio reads both formats and will keep reading ENC:v1:, so configurations you deployed keep working.

Which format your exports write is set in "Enterprise Administration" → "Format for encrypted secrets in exports". New installations start with the protected format. Installations that existed before v26.10.1 keep the compatible format until you switch, because versions before v26.10.1 take an ENC:v2: value for plain text and leave the key out.

Keep the compatible format until every device runs v26.10.1 or newer, then switch. You can also set the format centrally, for example, for every administrator who exports:

CONFIG["SETTINGS"]["DataApp.EnterpriseEncryptionExportFormat"] = "V1"

Change it to "V2" once the update has arrived everywhere. Switching doesn't change the values in your plugins. To protect a value you already deployed, export it again and replace it.

Changing the secret

When the secret on a device changes, AI Studio reloads all plugins and removes the keys of your configurations from the credential store, because they were decrypted with the old secret. Keys that users entered themselves stay. Change the secret and the encrypted values in your configurations together: export every key again with the new secret, and deploy the new configuration and the new secret at the same time.

Letting users bring their own key

Sometimes you want to hand out a provider with a fixed server, model, and name, but without a shared key: each user brings their own, for example, the key of their personal account. Set AllowUserProvidedAPIKey on the provider and leave out APIKey:

CONFIG["LLM_PROVIDERS"][#CONFIG["LLM_PROVIDERS"]+1] = {
    ["Id"] = "4f6b3a8e-2d4c-4b1a-9e5f-7a8b9c0d1e2f",
    ["InstanceName"] = "Our AI gateway",
    ["UsedLLMProvider"] = "SELF_HOSTED",
    ["Host"] = "VLLM",
    ["Hostname"] = "https://ai-gateway.intra.example.org",
    ["AllowUserProvidedAPIKey"] = true,
    ["AdditionalJsonApiParameters"] = "",
    ["Model"] = {
        ["Id"] = "openai/gpt-oss-120b",
        ["DisplayName"] = "GPT OSS 120B",
    },
}

• The provider stays managed: users can change only the API key. The settings page shows a key icon instead of the lock.
• It works the same for embedding and transcription providers. For embedding providers, the "Test" button stays available, so users can check their key.
• An APIKey on the same provider is ignored, with a warning in the log. Use different providers if you need both.
• When you withdraw the provider, AI Studio keeps the user's key in the credential store, in case the provider comes back.

Asking for the key on the start page

With PromptForUserAPIKey, AI Studio asks for the key itself. As long as such a provider has no key, the start page shows a panel with an input field, first and open, and AI Studio stays on the start page after starting, until the key is there. PromptForUserAPIKey includes AllowUserProvidedAPIKey.

    ["PromptForUserAPIKey"] = true,

• All providers of one configuration that set this option share one panel and one key: users enter the key once, and AI Studio stores it for each of them. Mark only providers that accept the same key, for example, several models behind one gateway. Providers that need another key belong in a configuration of their own.
• Before storing the key, AI Studio loads the models of the first of these providers that can list them. A key the provider rejects isn't stored, and the user is told so. When the provider can't be reached, AI Studio stores the key with a warning, so an outage doesn't stop anybody.
• This covers providers only. The keys of tools, such as web search, belong to the tool settings.

Explain how users get their key with CONFIG["USER_API_KEY_PROMPT"]. The Markdown text is required and appears above the input field; the title is optional:

CONFIG["USER_API_KEY_PROMPT"] = {
    ["Title"] = "Please add your API key",
    ["Markdown"] = [===[
        To use the AI models of Example Organization, you need a personal API key:

        1. Open the [AI portal](https://ai-portal.intra.example.org) and sign in.
        2. Open "Settings" and then "API keys".
        3. Create a key, copy it, and paste it below.
    ]===]
}

Prohibiting providers

Some organizations must not send any data to certain providers, for example, for legal reasons. List them, and AI Studio uses them neither for chats nor for embeddings or transcriptions:

CONFIG["SETTINGS"]["DataApp.ProhibitedProviders"] = { "<PROVIDER_KEY>" }

Replace <PROVIDER_KEY> with the keys of the providers you prohibit, as the example plugin lists them for DataConfidence.CustomConfidenceScheme. AI Studio ignores unknown names and logs a warning.

• A prohibition names the operator of an API, not the models. The models of a company may remain available through a hub that offers the models of several companies, or on a server of your own. Prohibit those as well if you need to.
• Users still find the provider. When they select it while adding a provider, the dialog explains that your organization doesn't allow it, and nothing can be saved.
• Providers set up before stay in the settings, marked as prohibited, and users can delete them. AI Studio no longer offers them and sends nothing to them: a chat that used one continues with another provider, and a data source whose embedding provider is prohibited is neither indexed nor searched until somebody selects another one. When you lift the prohibition, they work again.
• A prohibited provider is always untrusted, whatever the confidence scheme says.
• The list replaces, it doesn't add up. A configuration with a higher priority must repeat the providers of the base configuration, see How Central Configuration Works.
• Requires AI Studio v26.10.1 or newer. Older versions ignore the setting. Until all devices run v26.10.1, also use the CUSTOM confidence scheme, set the provider to UNTRUSTED there, and enforce a minimum confidence of at least VERY_LOW, see Confidence and Data Security.

Describing your own models

AI Studio knows what the models of the large companies can do: whether they read images, use tools, or reason, and how large their context window is. It can't know that about models of your own, such as a fine-tuned model, a model behind an internal name, or a server you configured differently from the model card. You can tell it in two ways.

For one provider: CapabilityOverrides

Use this to correct a detail of one provider, for example, a server that accepts no images, or a context window your operator configured smaller than the model card says:

    ["CapabilityOverrides"] = {
        ["MULTIPLE_IMAGE_INPUT"] = false,
        ["CONTEXT_WINDOW"] = 32768,
        ["MAX_IMAGES_PER_REQUEST"] = 4,
    },

Each key is optional and changes only what it names. The example plugin lists all keys. CONTEXT_WINDOW feeds the token count below the message field, so a wrong number misleads your users. Users can set the same values in the expert settings of a provider; for your providers, they see your values, locked.

Wherever the model appears: a model plugin

Use a model plugin when you run a model of your own and want AI Studio to treat it correctly everywhere, for every provider that serves it. A model plugin is a plugin with TYPE = "MODEL" and an ID of its own, which you put in a subfolder of your configuration archive, see Configuration Server. The example model plugin explains every field.

• An entry replaces everything AI Studio would otherwise say about the model names it matches. Write it as if AI Studio had never heard of these models. That's why CAPABILITIES is required, and why a single correction belongs in CapabilityOverrides instead.
• Write the pattern the way a model name is written: in lowercase, with hyphens between the parts. AI Studio rejects a pattern that could never match, and says why.
• Name the source and the date. SOURCE_URL and SOURCE_CHECKED_ON are required, so that whoever maintains the plugin later can check it.
• A model plugin only describes. It names no server, carries no key, and runs no code, so it needs no approval. Users can't import model plugins.
• When two of your model plugins describe the same model names, PRIORITY decides.

Where to go next

• Confidence and Data Security
• Enterprise IT