# Quickstart

> Sign in, connect a provider, create a gateway key and send your first request through ACOG in about ten minutes.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/get-started/quickstart. Last updated: 2026-10-16.

This guide takes you from nothing to a working request through the hosted service. On a self-hosted installation the steps are the same; replace `https://acog.tessarac.com` with your installation's address.

You need an account with at least one AI provider (for example an Anthropic API key, or a Google Cloud project with Vertex AI enabled).

## 1. Sign in and create your organization

Go to [acog.tessarac.com](https://acog.tessarac.com) and choose **Sign in or create your account**. The first time you sign in you are asked to name your organization. You become its admin.

Everything in ACOG belongs to an organization: provider connections, keys, usage, savings and invoices. Nothing is shared between organizations.

## 2. Connect a provider

1. Open **Admin → Providers** and choose **Connect provider**.
2. Pick the platform (Direct, Bedrock, Vertex, Azure or Custom) and the model family.
3. Enter the credentials. For Google Vertex AI and Anthropic you can choose **Keyless (workload identity)** instead of storing a key; see [Keyless connections](https://tessarac.com/docs/acog/providers/keyless-connections.md).
4. Review the models ACOG found in your account and choose a **default model**.

ACOG checks the credentials when you save. The secret is encrypted and is never shown again. The provider pages explain each platform's fields: [Anthropic](https://tessarac.com/docs/acog/providers/anthropic.md), [OpenAI](https://tessarac.com/docs/acog/providers/openai.md), [Google Vertex AI](https://tessarac.com/docs/acog/providers/google-vertex-ai.md), [AWS Bedrock](https://tessarac.com/docs/acog/providers/aws-bedrock.md), [Azure OpenAI](https://tessarac.com/docs/acog/providers/azure-openai.md) and [custom endpoints](https://tessarac.com/docs/acog/providers/custom-endpoints.md).

## 3. Switch on savings

A new hosted organization starts in **pass-through** mode: requests work, but they are forwarded unchanged at full price and nothing is saved. To switch the savings on, add a payment method under **Admin → Billing**. You are billed only a share of what ACOG measurably saves, monthly. See [Billing](https://tessarac.com/docs/acog/administer/billing.md).

You can do the rest of this guide first and add the payment method later.

## 4. Create a gateway key

1. Open **Developer** and create a key. Give it a name that says where it will be used, for example `laptop` or `billing-service`.
2. Copy the key. It starts with `acog_` and **is shown only once**: ACOG stores only a hash of it.
3. Store it as an environment variable:

```bash
export ACOG_API_KEY="acog_..."
```

A key you create for yourself carries your permissions and your usage is attributed to you. Admins can also create service keys for applications. See [API keys](https://tessarac.com/docs/acog/administer/api-keys.md).

## 5. Check the key

This call reaches no provider and costs nothing. It lists the models your key can use:

```bash
curl -s https://gateway.acog.tessarac.com/v1/models \
  -H "Authorization: Bearer $ACOG_API_KEY"
```

| Status | Meaning |
|---|---|
| `200` | The key works. The list is what it can route to; an empty list means no provider is connected yet. |
| `401` | The key was not read: it is missing, revoked, or in a header ACOG does not read. |
| `403` | The key is valid but lacks the gateway access permission (`proxy`). |
| `503` | ACOG could not reach its key store. This is not your key; retry. |

## 6. Send a request

Use any model you declared on a connection. ACOG speaks both the OpenAI and the Anthropic API, and translates between them, so either SDK can reach any of your models.

**curl (OpenAI-compatible)**

```bash
curl -s https://gateway.acog.tessarac.com/v1/chat/completions \
  -H "Authorization: Bearer $ACOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}]}'
```

**Python, OpenAI SDK**

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.acog.tessarac.com/v1",
    api_key=os.environ["ACOG_API_KEY"],
)

completion = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello"}],
)
print(completion.choices[0].message.content)
```

**Python, Anthropic SDK**

```python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://gateway.acog.tessarac.com",
    # Pass the gateway key as auth_token (sent as Authorization: Bearer), not api_key.
    auth_token=os.environ["ACOG_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
```

**Node.js, OpenAI SDK**

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.acog.tessarac.com/v1",
  apiKey: process.env.ACOG_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-4.1-mini",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);
```

The two base URLs differ only because of the path each SDK appends: the OpenAI SDK expects `/v1` in the base URL and the Anthropic SDK adds its own. See [Base URLs and authentication](https://tessarac.com/docs/acog/api/base-urls-and-authentication.md).

To let ACOG pick the model, send `"model": "auto"`. See [Auto mode](https://tessarac.com/docs/acog/optimize/auto-mode.md).

## 7. See the result

Open **Overview** in the console. Within a few seconds the request appears with its cost and what it would have cost sent directly. **Reports → Recent requests** shows each request's model, tokens, cost and saving.

## Next steps

- Point your coding assistant at ACOG: [Use ACOG with coding tools](https://tessarac.com/docs/acog/get-started/coding-tools.md).
- Set spending limits: [Budgets](https://tessarac.com/docs/acog/govern/budgets.md).
- Invite your team: [Users and invitations](https://tessarac.com/docs/acog/administer/users-and-invitations.md).