> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.consus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise SSO sign-in

> Install the Consus credential helper once. Your AI tools sign you in through the Consus portal with your company account and fetch their own key, so you never copy one.

> [!NOTE]
>
> **Enterprise feature.** SSO sign-in is available to organizations that have connected their identity provider (Okta, Microsoft Entra ID, Google Workspace, or another SAML/OIDC provider) to the Consus portal. If `portal.consus.io` doesn't recognize your account, ask your Consus admin, or contact [sales@consusindustries.co](mailto:sales@consusindustries.co) to set it up.

Every AI tool that talks to Consus Gateway needs a Consus API key. The usual way is to create a key in the portal and paste it into the tool's settings. Each integration page shows how.

There is an easier way. Install the **Consus credential helper** once. After that:

1. Your tool runs the helper whenever it needs a credential. Most tools have a setting for this.
2. The first time, the helper opens your browser to the Consus portal. You sign in with your company account and click **Approve**.
3. The portal issues a key to you. The helper keeps it on your computer and hands it to the tool.

You never see the key. Your admin doesn't need to push anything to your computer. Every request is tied to you, and your admin can revoke the key from the portal at any time.

The helper itself is a short shell script you can read in a minute. It holds no secrets of its own.

## Install

**macOS / Linux / WSL**

```bash theme={null}
curl -fsSL https://portal.consus.io/cli/install.sh | sh
```

This puts one script at `~/.consus/helper.sh`, readable by your user only. It needs `curl` and `openssl`, which every Mac and Linux machine already has.

**Windows (PowerShell)**

```powershell theme={null}
New-Item -ItemType Directory -Force "$HOME\.consus" | Out-Null
Invoke-WebRequest https://portal.consus.io/cli/helper.ps1 -OutFile "$HOME\.consus\helper.ps1"
```

Tools run it as `powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\<you>\.consus\helper.ps1`. Some tools (Claude Desktop, Codex) need a plain executable path instead. For those, also create `C:\Users\<you>\.consus\helper.cmd` with this one line:

```bat theme={null}
@powershell -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.consus\helper.ps1" %*
```

## Sign in

You can let your tool start the sign-in (its first request opens the browser), or do it now:

```bash theme={null}
sh ~/.consus/helper.sh login
```

The portal shows which tool and which computer is asking, for example *Factory on eric-mbp*. Check that it's the request you just started, then click **Approve** and close the tab.

> [!WARNING]
>
> Only approve a request you started yourself, on your own computer, a moment ago. If a sign-in link arrives any other way, don't approve it.

The key stays in `~/.consus/key` until it expires or you sign out. While it's there, the helper answers instantly and makes no network calls.

### Other commands

| Command | What it does |
| :- | :- |
| `sh ~/.consus/helper.sh status` | Shows who is signed in, the organization, and the key's label and expiry |
| `sh ~/.consus/helper.sh logout` | Forgets the key on this computer. The next request signs you in again |
| `sh ~/.consus/helper.sh --tool NAME` | Labels the key in the portal as `NAME - <computer>`. The per-tool settings below use this |
| `sh ~/.consus/helper.sh --wait SECONDS` | How long one run waits for you to finish signing in before it tells the tool to try again. Default 60 |

### Revoke a key

To disable a key everywhere, for example after losing a laptop, revoke it in the Consus portal. It's listed under your name with the tool and computer in its label. Admins can revoke any key in their organization.

## Set up your tool

Pick your tool. Each tab shows the one setting to change; the rest of that tool's setup is on its own integration page.

**Factory**

In `~/.factory/settings.json`, in each `customModels` entry (or in Factory's org-managed settings, which require this form):

```json theme={null}
"apiKeyHelper": "sh ~/.consus/helper.sh --tool factory",
"apiKeyHelperTtlMs": 60000
```

Full setup: [Factory](/integrations/factory).

**Claude Code**

In `~/.claude/settings.json` (or your gateway profile's settings file):

```json theme={null}
"apiKeyHelper": "sh ~/.consus/helper.sh --tool claude-code"
```

Claude Code re-runs the helper every five minutes. Full setup: [Claude Code](/integrations/claude-code).

**Claude Desktop**

In the third-party inference configuration, set **Credential kind** to **Helper script** and fill in:

| Field | Value |
| :- | :- |
| **Helper script** | `/Users/<you>/.consus/helper.sh` (Windows: the `helper.cmd` wrapper from the install step) |
| **Helper script arguments** | `--tool claude-desktop --wait 90` |
| **Credential helper timeout** | `120` seconds, so there is time to sign in |
| **Gateway auth scheme** | `x-api-key` |

Claude Desktop reads the key the helper prints and re-runs it on its refresh interval (one hour by default) and after a 401. Full setup: [Claude Desktop](/integrations/claude-desktop).

**Codex / ChatGPT desktop**

In `~/.codex/config.toml`, remove any `env_http_headers` or `http_headers` line that carries `x-api-key`, then add an `auth` table under the provider. Codex sends the helper's output as a bearer token, which the gateway accepts.

```toml theme={null}
[model_providers.consus.auth]
command = "/Users/<you>/.consus/helper.sh"
args = ["--tool", "codex", "--wait", "90"]
timeout_ms = 120000
refresh_interval_ms = 60000
```

The path must be absolute; `~` doesn't work here. Full setup: [Codex](/integrations/codex), [ChatGPT desktop](/integrations/chatgpt-desktop).

**Pi**

In `models.json`, a header value that starts with `!` is a command Pi runs at request time:

```json theme={null}
"headers": {
  "x-api-key": "!sh ~/.consus/helper.sh --tool pi"
}
```

Full setup: [Pi](/integrations/pi).

**OpenCode**

Sign in once with `sh ~/.consus/helper.sh login`, then point OpenCode at the key file:

```json theme={null}
"headers": {
  "x-api-key": "{file:~/.consus/key}"
}
```

Full setup: [OpenCode](/integrations/opencode).

**Everything else**

For tools that want a key in a settings field or an environment variable (Grok Build, Cline, VS Code Copilot, LiteLLM, the SDKs), let the helper supply it:

```bash theme={null}
export CONSUS_API_KEY="$(sh ~/.consus/helper.sh)"
```

Put that line in `~/.zshrc` or `~/.bashrc`. Every new shell gets a valid key, and the first one opens the browser to sign you in. For a settings field, run `sh ~/.consus/helper.sh login` and paste what it prints.

## How it works

* The helper creates a one-time secret and opens `portal.consus.io/cli/login` with a hash of it. The portal only ever sees the hash.
* When you approve, the helper redeems the secret with the portal. The portal mints a key for you through the same path as its own **Create key** button, and sends it to the helper once. The portal never stores the key.
* A sign-in request expires after ten minutes and can be redeemed once. Each helper run waits up to 60 seconds (change it with `--wait`). If signing in takes longer, the tool reports an auth error and succeeds on its next try.
* The helper only talks to `portal.consus.io`. Your tool only talks to `api.consus.io`.
* Everything the helper stores is in `~/.consus/`, readable by your user only: the key, and a small `meta.json` with your email, your organization, and the key's label and expiry.

## Troubleshooting

| What you see | Why | What to do |
| :- | :- | :- |
| The tool says it couldn't get a key from the helper | You hadn't finished signing in, or the helper path in the tool's settings is wrong | Finish signing in and try again, or run `sh ~/.consus/helper.sh login`. Check the path with `ls -l ~/.consus/helper.sh` |
| `403 Forbidden` from the gateway after a key was revoked | Tools keep the helper's last answer for a while | Run `sh ~/.consus/helper.sh logout`, wait for the tool's refresh interval (one minute with the settings above), then try again |
| The browser never opens (SSH session, container) | There is no desktop to open it on | The helper prints the sign-in link instead. Open it on any device, then try again |
| `Consus: sign-in expired or was already used` | More than ten minutes passed, or the request was already redeemed | Run it again. A fresh sign-in starts |
| `portal.consus.io` doesn't recognize your account | Your organization's SSO isn't connected yet | Ask your Consus admin |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.