Enterprise SSO sign-in

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 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:

Your tool runs the helper whenever it needs a credential. Most tools have a setting for this.
The first time, the helper opens your browser to the Consus portal. You sign in with your company account and click Approve.
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
Windows (PowerShell)

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.

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:

@powershell -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.consus\helper.ps1" %*

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

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.

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.

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

"apiKeyHelper": "sh ~/.consus/helper.sh --tool factory",
"apiKeyHelperTtlMs": 60000

Full setup: Factory.

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

"apiKeyHelper": "sh ~/.consus/helper.sh --tool claude-code"

Claude Code re-runs the helper every five minutes. Full setup: Claude Code.

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.

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.

[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, ChatGPT desktop.

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

"headers": {
  "x-api-key": "!sh ~/.consus/helper.sh --tool pi"
}

Full setup: Pi.

"headers": {
  "x-api-key": "{file:~/.consus/key}"
}

Full setup: OpenCode.

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:

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

Product

Getting Started

API Reference

Integrations

Install

Other commands

Revoke a key

Set up your tool

How it works

Troubleshooting

​Install

​Sign in

​Other commands

​Revoke a key

​Set up your tool

​How it works

​Troubleshooting

Install

Sign in

Other commands

Revoke a key

Set up your tool

How it works

Troubleshooting