# Connect the AI account your squad runs on

> Sign in with ChatGPT, connect a Claude subscription, or add an API key. Then choose the default model, add more accounts, and learn what happens at a limit and who bills the usage.

## The ways to connect

Your squad thinks with an AI account you connect. Your provider (the AI company, such as OpenAI or Anthropic) bills you for that usage. An API key is a secret code from your provider that lets SquadRoom use your account.

| Provider          | How you connect                              | What you need                                                                                                                      |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI Codex**  | ChatGPT sign-in, or an OpenAI API key        | A paid ChatGPT plan, such as Plus or Pro, or an OpenAI API key                                                                     |
| **Anthropic**     | Claude subscription, or an Anthropic API key | Claude Pro or Max and Claude Code, or an Anthropic API key                                                                         |
| **Azure OpenAI**  | API key                                      | Your Azure key, your endpoint URL (your Azure OpenAI web address), and your deployment names (what you named your models in Azure) |
| **Google Gemini** | API key                                      | A Google AI API key                                                                                                                |
| **OpenRouter**    | API key                                      | An OpenRouter API key                                                                                                              |

Your workspace runs on one provider at a time: the **Active Provider**. Other connected accounts wait until they are needed. See [What happens when an account hits its limit](/docs/connect-your-ai#what-happens-when-an-account-hits-its-limit).

## Where you connect

- **During setup**, on **STEP 3 OF 6**. Follow Step 5 in [Set up SquadRoom and get your first report](/docs/get-started#step-5-connect-your-ai-account).
- **Any time later**, in **Settings > Model Providers**, under **Language Models**. The steps on this page are for Settings.

In Settings, each provider row shows one label:

| Label         | Meaning                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Set up**    | Nothing is connected.                                                                                                                 |
| **Connected** | At least one account works.                                                                                                           |
| **Reconnect** | The provider refused an account's sign-in or key. See [Fix a sign-in that expired](/docs/connect-your-ai#fix-a-sign-in-that-expired). |

## Connect an account

<!-- tabs -->

#### ChatGPT

Your squad runs on your ChatGPT plan, instead of an API key that is billed for each use. You approve the connection with a device code: a code SquadRoom shows you, which you paste on ChatGPT's own page.

##### Before you begin

In ChatGPT, open **Settings > Security** and turn on **Device code authorization for Codex**. This setting lets ChatGPT accept the code. For a short video, click **Show me how**.

##### Connect

1. Open **Settings > Model Providers** and click **OpenAI Codex**.
2. Click the **ChatGPT account** tab.
3. Click **Sign in with ChatGPT**. A code shows under **Enter this code at ChatGPT**.
4. Copy the code.
5. Click **Open ChatGPT**. ChatGPT opens in a new tab.
6. Sign in to ChatGPT if it asks, paste the code, and approve.
7. Go back to SquadRoom. The window closes once you approve.

The account is saved under its name, usually your ChatGPT email. If it is your first OpenAI Codex account, or none was in use, your workspace now runs on it. Otherwise it waits to take over when the account in use hits its limit. Click **Use** to switch to it now.

To stop before you approve, click **Cancel**.

#### Claude subscription

Your squad runs on your Claude Pro or Max plan, instead of an API key that is billed for each use. You make a token with Claude Code on your computer and paste it into SquadRoom. A token is a secret code that lets SquadRoom use your Claude plan.

##### Before you begin

Claude Code is Anthropic's tool for the terminal, the app on your computer where you type commands. To install it, run this in the terminal:

```
npm install -g @anthropic-ai/claude-code
```

##### Connect

1. Open **Settings > Model Providers** and click **Anthropic**.
2. Click the **Claude subscription** tab.
3. In a terminal, run this command:

   ```
   claude setup-token
   ```

4. Approve the sign-in in your browser. The terminal prints a token that starts with `sk-ant-oat01-`.
5. Copy the token and paste it under **Paste the token**.
6. Optional: type a name in **Account name**. Without one, it is called "Claude Subscription".
7. Click **Connect Claude**.

The window closes. The first time you connect a Claude subscription, your workspace switches to it. If the token isn't accepted, the window stays open with an error, such as "Failed to connect Claude subscription."

#### API key

Use an API key for Azure OpenAI, Google Gemini, or OpenRouter, or as the other way to connect OpenAI or Anthropic. The provider charges for each request your squad sends, at its own prices.

1. Open **Settings > Model Providers** and click the provider. For **OpenAI Codex** and **Anthropic**, stay on the **API Key** tab.
2. Under **Add an API key**, type a name, such as "OpenAI Codex personal". Without one, it is called "Key" and a number.
3. Paste the key into the key field. The eye button shows or hides it.
4. For **Azure OpenAI**, also fill in **Azure endpoint URL** and **Deployed models**, your deployment names separated by commas.
5. Optional: click **Verify**. It shows **Valid** when the key has the right format.
6. Click **Add API Key**. You see "API key added."

<!-- /tabs -->

## Choose the default model

Your squad uses the default model, the AI it thinks with, unless you pick another. Set it in **Settings > Model Providers** under **Model Defaults**.

1. Under **Active Provider**, click the provider your workspace should run on.
2. Under **Default Model**, pick a model.
3. Under **Reasoning Level**, pick a level.
4. Click **Save Defaults**. You see "Defaults saved successfully."

**Save Defaults** stays grey until you pick a model. If you see "Failed to save defaults.", click it again.

> **Warning:** **Save Defaults** puts the **Default Model** on every squad member, including one you gave its own model on **Squad**. Pick that squad member's model again afterwards.

### The model list

The list starts with one model marked **Recommended**, then the provider's latest models. To find an older one, click **Show all** and the number of models. For Azure OpenAI, the list shows the deployment names you entered.

### Reasoning levels

This sets how much the model thinks before each reply.

| Level                       | What it does                                          |
| --------------------------- | ----------------------------------------------------- |
| **Automatic** (the default) | A balanced amount of thinking on every reply.         |
| **Low**                     | Quicker, cheaper replies, with less thinking.         |
| **High**                    | More thinking on every reply. Slower, and costs more. |
| **Standard**                | No extra thinking. Fastest and cheapest.              |

### Use a different model for one squad member or one chat

- **For one squad member:** on **Squad**, open the squad member and pick a model under **Default Model**. You see "Default model updated".
- **For one conversation:** in **Chat**, click the model name or the reasoning level in the message box and pick another.

## Add more accounts

An extra account can take over when the one in use hits its limit.

| To add                         | Do this                                                                                                                                                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Another ChatGPT account        | In **OpenAI Codex**, on **ChatGPT account**, click **Add another ChatGPT account**. Before you approve, sign out of ChatGPT or use a private window, or ChatGPT approves the account you already connected. |
| Another API key for a provider | Add it under **Add an API key**.                                                                                                                                                                            |
| Another provider               | Open its row under **Language Models** and connect it.                                                                                                                                                      |

> **Warning:** Connecting a provider for the first time switches your workspace to it. So does adding an API key to a provider your workspace doesn't run on. To switch back, pick the provider under **Active Provider** and click **Save Defaults**.

### Manage a ChatGPT account or a Claude subscription

| State               | Meaning                              |
| ------------------- | ------------------------------------ |
| **Active**          | Your workspace runs on this account. |
| **Available**       | Saved and ready.                     |
| **Sign-in expired** | The provider refused this account.   |

- **Use** (ChatGPT) switches your workspace to that account. You see "Now using" and its name.
- The **...** menu has **Rename**, **Update token** (Claude), and **Disconnect**.
- **Update token** replaces a Claude token. Paste the new one from `claude setup-token` and click **Save token**. The account keeps its name.

### Manage API keys

Saved keys are listed under **Rotation order**: the order SquadRoom uses them in, top to bottom. The key at position 1 is in use until it runs out, then the next key takes over.

- The up and down arrows move a key.
- The pencil replaces a key. Type a new key, or leave the field empty to keep the key and only change its name. Click **Save Changes**. You see "API key updated."
- The bin deletes a key. To delete the key at position 1, move another key to the top first.

## What happens when an account hits its limit

SquadRoom moves on in this order:

1. **Another account of the same provider takes over.** Your ChatGPT accounts and OpenAI keys take over from each other. Other API keys of the same provider take over in **Rotation order**.
2. **Your fallback providers are tried in order.** A fallback is another provider your squad switches to when every account of the one in use hits its limit. You set them under **Fallback Providers** in **Model Defaults**. Click a provider to add it, pick its model, order them with the arrows, and click **Save Defaults**. Only a provider connected with an API key can be a fallback.
3. **The work waits.** The task goes back to **Queued** and starts again on its own when the limit resets. You don't need to do anything.

While work waits, the task's activity and a notification say your plan hit its usage limit. They also say when work starts again, such as "at 3:10 PM". In Chat, the message that couldn't be answered tells you when to send it again. When the provider is too busy instead, the message says so, and also says when work starts again.

## Fix a sign-in that expired

When a provider refuses an account, its row shows **Reconnect**.

| Account             | What you see                              | What to do                                              |
| ------------------- | ----------------------------------------- | ------------------------------------------------------- |
| ChatGPT             | **Sign-in expired** and **Sign in again** | Click **Sign in again** and approve in ChatGPT.         |
| Claude subscription | **Sign-in expired** and **Update token**  | Run `claude setup-token` again and paste the new token. |
| API key             | **Key rejected**                          | Click the pencil and paste a new key.                   |

Its tasks show "model provider sign-in failed, reconnect it in Settings". A task tries again on its own, then stops after it fails several times. Once you reconnect, select **Retry** on it or add a comment.

## See how much is left

Open **Settings > Usage** and find the **Model accounts** card, or click your name at the bottom of the sidebar, then **Usage**. **Refresh** updates it.

A ChatGPT account shows its limits as bars, such as **5-hour** and **Weekly**, each with the percent left and when it resets. Each account also shows its role:

| Role                       | Meaning                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| **In use now**             | Your workspace runs on this account.                                                      |
| **Ready to take over**     | It takes over when the account in use hits its limit.                                     |
| **Saved, not in rotation** | Saved, but it won't take over now, for example because its provider isn't the one in use. |
| **Sign-in expired**        | The provider refused it.                                                                  |

## Who bills the usage

| How you connect     | Who bills you                       | What counts                                                                                                        |
| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| ChatGPT sign-in     | OpenAI, through your ChatGPT plan   | Your squad's work counts against your plan's limits.                                                               |
| Claude subscription | Anthropic, through your Claude plan | Your squad's work counts against your plan's limits.                                                               |
| API key             | The provider that gave you the key  | Each request, at the provider's prices.                                                                            |
| SquadRoom           | SquadRoom                           | Your SquadRoom plan and research credit packs only. See [What SquadRoom costs and what uses credits](/docs/costs). |

## Image models

**Image Models**, on the same page, sets up how your squad makes images. It is separate from the account your squad runs on.

## Disconnect an account

- **A ChatGPT account or a Claude subscription:** open the **...** menu and click **Disconnect**. If it was in use, SquadRoom switches to another account of the same provider first, then to another provider.
- **An API key:** click the bin.

> **Warning:** If you disconnect the last account, your squad can't work until you connect one again.

## What SquadRoom doesn't do

- It doesn't bill you for model usage, and research credits never pay for it.
- It never asks for your ChatGPT or Claude password. ChatGPT uses a code, and Claude uses a token from your own terminal.
- It never shows a key or token again after you save it. SquadRoom stores them encrypted.
- **Verify** doesn't test a key with the provider. It checks the format only, so a key that passes can still be refused.
- A workspace holds one Claude subscription at most, 10 API keys per provider, and 5 fallback providers.
- It doesn't show a balance for an API key, because the provider doesn't share one.

## If something goes wrong

### "Rate limited by OpenAI. Please wait a moment before generating a new code."

**Cause:** You asked OpenAI for codes too quickly.

**Fix:** Wait a moment, then click the sign-in button again.

### "Device authentication failed."

**Cause:** The ChatGPT sign-in didn't finish.

**Fix:** Start again from the sign-in button.

### "[Account] was already connected, so its credentials were refreshed. To add a different subscription, sign out of ChatGPT (or authorise in a private window) first."

**Cause:** ChatGPT approved the account you had already connected.

**Fix:** Sign out of ChatGPT, or use a private window, then sign in with the other account.

### "[Account] was saved, but the workspace could not be told to rotate onto it. Open Default Model and press Save to finish."

**Cause:** The account is saved, but it can't take over yet.

**Fix:** Click **Save Defaults** under **Model Defaults**.

### "This is a browser authorization code. Paste this code into your terminal at the 'Paste code here' prompt, press Enter, then copy the token starting with 'sk-ant-oat01-'."

**Cause:** You copied the code from the browser, not the token.

**Fix:** Paste the code into the terminal, press Enter, and copy the token the terminal prints.

### "The setup token must start with 'sk-ant-oat01-'. Run 'claude setup-token' in your terminal to generate one."

**Cause:** You pasted something else, such as an API key.

**Fix:** Run `claude setup-token` and paste the token it prints. For an API key, use the **API Key** tab.

### "This doesn't look like a valid [provider] key."

**Cause:** **Verify** found a key that isn't in your provider's format:

| Provider      | The key must                 |
| ------------- | ---------------------------- |
| OpenAI Codex  | Start with `sk-`             |
| Anthropic     | Start with `sk-ant-`         |
| Google Gemini | Start with `AIz`             |
| OpenRouter    | Start with `sk-or-`          |
| Azure OpenAI  | Be longer than 10 characters |

**Fix:** Copy the whole key again from your provider, with no spaces.

### "Base URL is required"

**Cause:** An Azure key needs **Azure endpoint URL**.

**Fix:** Fill in the endpoint of your Azure OpenAI resource.

### "Deployed Models list is required for Azure"

**Cause:** An Azure key needs at least one deployment name.

**Fix:** Type your deployment names in **Deployed models**, separated by commas.

### "An account named [name] already exists for this provider"

**Cause:** Another key for this provider has that name.

**Fix:** Pick another name.

### "Delete one of the 10 saved keys before adding another."

**Cause:** The provider already holds 10 keys.

**Fix:** Delete a key with the bin, then add the new one.

## Related pages

- Messages you see during setup: [When setup won't finish](/docs/setup-problems).
- One squad member's model: [Add, change, and pause squad members](/docs/squad).
- The model for one conversation: [Chat with your squad](/docs/chat).