AI connection credentials

How to get one AI connection created, credentialled, verified and active - the base URL shape, what exactly to paste as the credential, and the per-family gotchas that account for most failed probes. For the families themselves and the native-or-gateway choice, see AI providers.

Adding an AI connection

In the frontend, open the client, then the AI Providers tab. Its left menu has four sub-sections - Connections, Logical models, Purposes and Review passes. Start in Connections. The create button there is labelled Add Profile; the object it creates is what these pages call an AI connection.

1. Choose the provider family. The dropdown offers only families this build has a driver for and the tenant permits. Anything else is absent, not disabled. An existing connection whose family is no longer available is flagged Unavailable, and reviews that would use it are refused.
2. Enter the base URL. It is stored exactly as entered. The form shows the expected shape per family.
3. Enter the credential. The form shows the fields the selected family needs for the selected authentication mode. See Credentials by provider.
4. Verify. ProPR probes the endpoint and reports what is wrong when the probe fails.
5. Add models. Either discover them from the provider, browse the model catalog, or define one by hand - see models and the catalog. To find a mistyped model id or one the key may not use before a review does, check up to three models per request: each selected model is called once with a few tokens.
6. Activate it. A connection is created inactive, and activation is refused until the connection has been verified since its last change. While it is inactive, its purpose bindings are invisible to the review loop - the second resolution layer described under AI purposes only looks at active connections.
7. Point a logical model at one. A connection with models attached does nothing until a logical model names one of those models and a purpose or a review pass uses that name - see purposes.

More than one connection can be active at the same time, so a single client can mix providers. Which model does which work is decided by logical models, not by which connection was activated last.

Verified profile updates

The client API provides POST /clients/{clientId}/ai-connections/{connectionId}/verify-update for profile edits that must retain working routing. It accepts the same optional settings as the profile PATCH operation. Only client-owned profiles with supported provider and authentication combinations can use this operation; tenant and managed-authentication profiles require administrator configuration. Omitted or blank credential fields reuse the protected saved credential. ProPR validates and verifies the unsaved candidate before replacing the saved configuration and verification snapshot. A failed verification leaves the saved profile and active bindings unchanged. A concurrent credential, model or profile edit returns 409; reload the connection before retrying.

Client model selection

POST /clients/{clientId}/ai-connections/select-purposes accepts default, high and embedding, each with connectionId and configuredModelId. All selected connections must belong to the client and be verified. Default and High require chat models. Embedding requires embedding capability, a tokenizer, a positive input limit and 1536 dimensions, the width ProPR stores embedding vectors with. Both the configured model and its provider driver must support the selected chat or embeddings protocol.

ProPR applies Review default, Triage, Verification, Low effort, Medium effort and Memory reconsideration to Default. High effort uses High, and Embedding default uses Embedding. ProPR activates selected connections and updates these bindings in one transaction. It preserves other purposes, logical models, tenant connections and client connections that use managed authentication. A conflicting logical purpose mapping or higher-priority managed binding returns 409 with a safe action and the affected purposes. Update those mappings in the ProPR console before applying the client selection.

Selected models remain in effect after a restart. Explicit logical-purpose mappings take precedence over connection bindings. A conflicting selection returns 409 and preserves the saved bindings. Reload the current configuration before retrying.

Tenant machine credentials can call these client-scoped operations after current client ownership is checked. They cannot modify logical-model mappings or inherited connections through these operations.

Tenant-owned connections

The steps above create a connection owned by one client. A tenant administrator can instead define one on the tenant, under Tenant → Connections: the same provider, base URL, credential and models, verified the same way.

A tenant connection is deliberately thinner. It has no purpose bindings and no activation, because it is only ever reached through a tenant-catalog logical model - see Two layers. Every client in the tenant inherits those names; the connection behind one shows in a client’s own logical-model list as Tenant-managed and cannot be opened or edited from there.

One caveat, about edition and not about a capability key: a Community installation has no tenant layer to define either object on, so define connections and logical models on the client there - see editions.

Credentials by provider

One row per authentication mode a family declares. The form offers the modes of the family selected, and shows the fields of the mode selected.

Credentials are encrypted at rest and never shown again. On the form, re-entering a credential replaces it; leaving the fields untouched keeps the stored one. A required field left empty is refused at save time and the refusal names the field, as is a field the family does not use.

Provider-specific setup notes

Azure OpenAI

Use meisterdev/azureOpenAi for every Azure-hosted endpoint, including Azure AI Foundry endpoints the portal labels an “OpenAI endpoint”. Configuring one of those under meisterdev/openAi is refused with a message telling you which family to use.

Azure is also the one family whose host is restricted outright, not guarded at connect time. Which hostnames that accepts, and why, is under outbound request protection.

OpenAI

https://api.openai.com/v1 with an API key. This family is for OpenAI’s own endpoints only; an Azure-hosted URL under it is refused, as above.

LiteLLM and OpenAI-compatible

Both take the base URL you supply and the key that endpoint expects. Model ids are whatever the gateway or server exposes, not what the upstream vendor calls them.

meisterdev/openAiCompatible is deliberately assumed to serve the chat-completions surface only, which also narrows what a model attached to such a connection may claim - see protocol mode.

A self-hosted endpoint on a private address - Ollama, vLLM, an internal gateway - is refused until MEISTER_ALLOW_PRIVATE_EGRESS is set. What that opt-in does and does not permit is under outbound request protection; the variable itself is in configuration.

Anthropic

Anthropic rejects a bearer token, so any authentication mode other than the API key above is refused on the form instead of failing with a 401 on the first call.

Anthropic serves no embedding models. If you review on Anthropic, point the Embedding default purpose at a model on a different connection. Nothing stops you saving an Anthropic connection without one - the refusal comes at the first embedding call, with a message telling you to bind that purpose elsewhere - so check it during setup rather than discovering it when thread memory silently stops working.

The base URL is not pinned to Anthropic’s own host. The Messages protocol is also served by enterprise proxies and by gateways configured to pass it through, and pointing this family at one of those keeps the native behaviour - including the cache breakpoints an OpenAI-shaped route loses.

AWS Bedrock

Name the region in the host: https://bedrock-runtime.eu-central-1.amazonaws.com runs inference in Frankfurt. An AWS host that names no region is refused at save time, and that check reads the host and nothing else - a region default query parameter will not satisfy it. AWS China hosts (*.amazonaws.com.cn) count as AWS hosts too.

The region=<region> default query parameter exists for a private or VPC endpoint, permitted by the private-egress opt-in, whose host is not an AWS host and therefore names no region.

Leave that parameter unset on an AWS host. When both are present the query parameter wins, so a connection on bedrock-runtime.eu-central-1.amazonaws.com carrying region=us-east-1 sends your code to Virginia. The host is what you read to see where a connection points; it is not what enforces it.

Model discovery also needs an AWS host; on a private or VPC endpoint, enter the models by hand. Discovery against AWS notes that some models can only be called through an inference profile - where your account requires one, use the profile id as the model id.

The credential is always the one you store. ProPR never falls back to the AWS credentials of the machine it runs on: in a multi-tenant installation that identity belongs to the operator, not to the tenant whose review is running, so a connection without its own access key is refused instead of quietly billed to someone else’s role.

Google Gemini and Vertex AI

Two different front doors. A connection’s host decides which one it reaches, and no setting could disagree with the URL:

• Vertex AI - https://<location>-aiplatform.googleapis.com, or https://aiplatform.googleapis.com for the global endpoint, with a required project=<your-gcp-project> default query parameter, the Google Application Default Credentials authentication mode and a Google credential JSON document. That is a service-account key for most installations, and a workload-identity configuration where the identity is federated; ProPR reads which one it is from the document’s own type.
• Gemini API - https://generativelanguage.googleapis.com with the API Key mode and a plain API key, no project needed.

The authentication mode must match the host, and a connection whose mode belongs to the other surface is refused at save time. The Gemini API reads its credential from a header, so a Gemini connection holding a service-account document would send that document’s private key in one.

A Vertex host names the location inference runs in, so the host pins where the data goes. A host naming no location addresses the global endpoint, and Google serves its newest models there only, so a model a region refuses with Publisher model ... was not found may still be available globally. Vertex has no model listing on this surface, so enter the model ids you intend to use by hand. A Gemini API connection must target a *.googleapis.com host unless the private-egress opt-in is on.

Troubleshooting

Verification failures

A failed probe reports a category and, where one applies, what to change.

Common messages

A model that verifies and calls cleanly but reports no context window or price is a catalog problem and not a credential one - see a model is missing its context window or price. Reviews that run but cost more than expected are covered in controlling cost.

For a symptom that is not about this connection, start from troubleshooting.