Key concepts

Organization

An organization is a tenant. Every connection, key, budget, cache entry, usage record and invoice belongs to exactly one organization, and nothing is shared between organizations. You can belong to more than one; the organization switcher at the top of the sidebar moves between them.

Provider connection

A connection is one set of credentials for one platform and one model family, for example Anthropic models on Google Vertex AI in project my-project or GPT models on Azure OpenAI resource my-resource. Platforms are called channels in the API:

Channel	Model families
direct	anthropic (the Anthropic API), openai (the OpenAI API)
bedrock	anthropic (models on AWS Bedrock)
vertex	anthropic (Claude on Vertex AI), gemini
azure	openai (Azure OpenAI)
custom	compatible (any OpenAI-compatible server)

An organization has at most one connection per channel and family. Credentials are encrypted at rest and can be replaced but never read back.

Declared models

Each connection declares the models it serves. Routing is by model: the model field of a request selects the connection that declared it. You never choose a provider in a request; you choose a model.

• A declared id ending in * matches any model id with that prefix, and * alone matches every model.
• A version suffix is matched loosely: a request for claude-haiku-4-5 reaches a connection that declared claude-haiku-4-5@20251001, and the other way round. A match never crosses model families or major versions.
• A model that no connection declares is refused with 409 model_not_configured.

If several connections declare the same model, ACOG spreads requests across them and fails over between them. See Routing and failover.

Default connection and default model

One connection is the organization’s default, and each connection has a default model. A request for model: "auto" goes to the default connection’s default model when auto mode is off. A model that the default connection declares is always served by the default connection.

Gateway key

A gateway key (acog_…) authenticates requests to the gateway and to the management API. There are two kinds:

Key type	Who uses it	Usage is attributed to	Limits and model rules
User key	A person	That person	Their per-person limits apply
Service key	An application, script or bot	The key	Set on the key itself

A key carries scopes, which are permissions. A key needs the proxy scope to call the gateway. A key never has more permissions than the person who created it. See API keys.

Application

An application is a name for traffic, such as support-bot or nightly-etl. Assign service keys to it and every request made with those keys is reported under that application, in reports and in traces. Attribution comes only from the key: no request header can change it. Requests from keys with no application are reported as unattributed. See Applications.

Team

A team groups members below the organization. Budgets, rate limits and model access can be set per team. In the budgets API a team is called a group. See Teams.

Scopes of control

Governance rules attach to scopes, from broadest to narrowest:

Rule	Scopes
Model access	Organization, team, user, service key
Budgets	Organization, team (group), user
Rate limits	Organization, application, team, user, service key
Data loss prevention rules	Organization, team, user, application

A narrower scope can only tighten what a broader one allows.

Request outcome (disposition)

Every request is recorded with how it was served:

Disposition	Meaning
Exact cache	Answered from the response cache; no upstream call
Semantic cache	Answered from the semantic cache; no upstream call
Dedup	Shared an identical in-flight request’s upstream call
Optimized	Forwarded with savings applied (prompt caching, cleanup, routing)
Batch	Served by the provider’s batch service
Pass-through	Forwarded unchanged