API Keys and Scripting

Agents, CI jobs, and scripts shouldn't depend on an interactive login. That's what company API keys and COFOUNDER_API_TOKEN are for.

API keys

Creating keys isn't available over MCP, so create them from the CLI or API, then hand them to your agent's environment. Creating, listing, and revoking keys all need a signed-in admin; a key can't manage other keys.

cofounder company api-keys create --name deploy-bot

The key prints once. Store it somewhere safe, because list only ever shows names and prefixes. A key authenticates as the company it was minted under.

Use the token

Use the key for CLI and REST API requests. Native MCP connections use their host's separate OAuth login:

export COFOUNDER_API_TOKEN="cfk_..."
cofounder company show   # authenticates as the key's company

To check which key is in use, cofounder company api-keys current shows the key's id, its company, and who created it, never the secret.

From a signed-in CLI, cofounder auth token prints a session token for one-off use. The token does not carry the CLI's saved company selection; direct REST requests must also send X-Organization-Id with the intended company UUID. Reach for company API keys for anything durable: they survive logouts, and you can revoke them independently.

Give each runtime or job its own named key. For temporary jobs, pass an ISO 8601 expiry with --expires-at when creating the key, then revoke it after the job. Omitting expiry creates a key with no expiration.

Cloud network secrets

An MCP login does not automatically authenticate a CLI process in a sandbox. If your runtime substitutes a network-secret placeholder for an API key, configure its API destination and supply the credential type and expected company separately:

export COFOUNDER_API_TOKEN_KIND=company_api_key
export COFOUNDER_COMPANY_ID="<company-uuid>"
# COFOUNDER_API_TOKEN is supplied by the runtime's secret injection.
cofounder auth whoami --json

The CLI sends the expected company with requests; the server rejects a key bound to a different company. Verify the returned company before starting work. Runtime network substitution must be configured and tested separately from the CLI.

Or skip the CLI and call the API directly:

curl -H "Authorization: Bearer $COFOUNDER_API_TOKEN" \
  https://api.superoptimizers.cofounder.co/cofounder-cli/v1/company

Scripting

Commands print machine-readable JSON on stdout, stable enough to parse with jq or feed to another agent. Errors are a JSON object on stderr, and progress goes to stderr:

cofounder company resources list | jq '.resources[].status'

--json is accepted as a no-op. company switch is the exception: it needs an interactive terminal, so scripts should use company list and company use <org-id-or-slug>. Non-zero exits still mean failure, so scripts can trust exit codes.

Environment variables

See CLI Environment Variables for the variables the CLI reads.