Connecting providers
How provider connections work: platforms and model families, declared models, the default connection, and how ACOG stores your credentials.
ACOG calls AI providers only with credentials your organization owns. A connection holds those credentials for one platform and one model family. Open Admin → Providers to see your connections and Connect provider to add one. You need the Connect and disconnect AI provider accounts permission (admin:providers).
Platforms and model families
| Platform | Model families | Credentials | Page |
|---|---|---|---|
| Direct | Anthropic | API key, or keyless (workload identity federation) | Anthropic |
| Direct | OpenAI | API key | OpenAI |
| Google Vertex AI | Anthropic (Claude), Gemini | Service account key, or keyless (workload identity federation) | Google Vertex AI |
| AWS Bedrock | Anthropic and other Bedrock models | Access keys, or a role ACOG assumes | AWS Bedrock |
| Azure OpenAI | OpenAI | API key | Azure OpenAI |
| Custom | OpenAI-compatible | Optional API key | Custom endpoints |
A platform that hosts several families needs one connection per family. Claude and Gemini in the same Google Cloud project are two connections.
An organization has at most one connection per platform and family. Saving a new connection for a platform and family that already has one replaces its credentials.
The connect wizard
- Provider. Choose the platform and model family.
- Credentials. Enter the credentials and the platform’s settings (region, project, endpoint). ACOG checks them before saving.
- Review models. ACOG lists the models your account can call and you choose which ones this connection serves, and its default model. If the listing is not available you can enter model ids by hand.
Models must be enabled in your own provider account (Bedrock model access, Vertex AI Model Garden, an Azure deployment). If a request is refused because a model is not enabled, ACOG answers 422 model_access_required with instructions for that platform.
Declared models
The models a connection serves are its declared models. A request’s model selects the connection that declared it. The list is open: you can declare any model id, including one released after you connected, and a declared id ending in * matches every id with that prefix.
Declaring a model only tells ACOG it may send that model to this connection. Your provider decides whether your account may call it.
ACOG checks each connection once a day and tells your admins when the provider offers models the connection does not declare, or no longer serves one it does. It never changes a connection for you. To turn the check off, clear Daily model check under Admin → Webhooks.
The default connection
One connection is your organization’s default. Your first connection becomes the default automatically. To move it, choose Set as default on another connection. There is always exactly one default while any connection exists.
The default matters in two ways:
- A request for
model: "auto"(with auto mode off) goes to the default connection’s default model. - A model the default connection declares is served only by the default connection, with no spreading or failover to other connections. See Routing and failover.
How credentials are stored
- Secrets (API keys, service account keys, AWS secret keys) are encrypted with AES-256-GCM before they are stored, and are bound to your organization and the connection’s platform and family.
- Secrets are write-only. The console shows a masked hint such as
••••a1b2, never the secret. - Keyless connections store no secret at all.
Changing or removing a connection
You can edit a connection’s settings, models and default model at any time; changes apply from the next request. To rotate a credential, enter the new one and save.
Disconnect removes the connection. Models it declared stop resolving until another connection declares them, and requests for them fail with 409 model_not_configured.
Hosted service: what ACOG can reach
The hosted service calls providers from the public internet. A connection’s base URL, endpoint or token issuer must be a public address on port 443 with HTTPS. Private, LAN and loopback addresses, other ports and http:// URLs are refused when you save, and a name that later resolves to a private address is not called (409 connection_not_usable). To use a model server on your own network, put it behind a public HTTPS address you control, or run ACOG self-hosted, which calls any address you configure.