API Keys and Scripting

A company API key lets agents, CI jobs, and scripts act for one company without anyone signing in. Put it in COFOUNDER_API_TOKEN and the CLI and API use it.

Create and Manage Keys

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

Create company:operate keys from the CLI or API, then hand them to your agent's environment. MCP connections sign in with OAuth and don't need one, so over MCP your agent can create only keys bound to one app: forms:submit for a site's forms or email:send for an app's email. Creating, listing, and revoking keys need a signed-in admin. A key can't manage other keys.

The key prints once, so store it right away. list shows only names and prefixes. A key acts as the company it was created under.

Give each runtime or job its own named key. For temporary jobs, pass an ISO 8601 expiry with --expires-at, then revoke the key after the job. Without --expires-at, the key never expires.

Use a Key

Use the key for CLI and REST API requests. MCP hosts sign in with their own OAuth login. For an agent with no browser, cofounder mcp setup points the MCP connection at the key instead (see MCP Configuration).

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

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

To skip the CLI, call the API directly:

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

One-Off Session Tokens

From a signed-in CLI, cofounder auth token prints a session token for one-off use. It doesn't carry the CLI's saved company, so direct REST requests must also send X-Organization-Id with the company's UUID. Use company API keys for anything lasting, because they survive logouts and you can revoke them one by one.

Cloud Network Secrets

An MCP login doesn't sign in a CLI running in a sandbox. If your runtime swaps in a network-secret placeholder for the API key, configure its API destination and tell the CLI the key type and expected company:

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 each request, and the server rejects a key for a different company. Check the returned company before starting work. Set up and test the runtime's secret substitution separately from the CLI.

Script the CLI

Commands print JSON on stdout, stable enough to parse with jq or pass to another agent. Errors print as a JSON object on stderr, along with progress messages. A non-zero exit always means failure.

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

--json is accepted and changes nothing. company switch needs an interactive terminal, so scripts should use company list and company use <org-id-or-slug>.

For the variables the CLI reads, see CLI Environment Variables.