API keys & authentication

Every interaction with Ntropii Workspace — every CLI command, every MCP tool call, every SDK method — authenticates with an API key.

How keys are scoped

API keys are tenant-scoped. One key gives access to exactly one tenant; if you administer three tenants, you’ll have three keys. The organisation that owns the tenant is recorded as provenance, but it is not an authorisation boundary. This matters because:

A leaked key compromises one tenant’s surface area, not your whole organisation.
Different teams within an organisation can hold different keys for different tenants without seeing each other’s runs.
Rotation is per-tenant — you can rotate a key without disturbing other tenants.

Generate a key

ntro auth login

Walks you through:

Pick a connection name

Used in ~/.ntro/config.toml as [connections.<name>]. local, staging, and production are conventional. You can have as many as you like.

Enter the host

https://api.ntropii.com/v1 for production.

Paste the API key

You generate the key in the Ntropii web UI under Settings → API keys. The CLI does not mint keys directly.

Pick a default tenant

Most CLI commands target a tenant. Setting a default at login skips having to pass --tenant on every call. Override with -c connection, --tenant slug, or NTRO_TENANT.

Verify the key works:

ntro auth whoami
# → identity, organisation, accessible tenants

For non-interactive setups (CI/CD pipelines, headless installs), pass everything as flags:

ntro auth login --no-interactive \
  --name production \
  --host https://api.ntropii.com/v1 \
  --api-key ntro_prod_abc123 \
  --default-tenant acme-fund

Where the key gets used

The same key works across all three surfaces:

CLI
MCP server
SDK (Python)

Picked up automatically from ~/.ntro/config.toml based on the active connection. Override with --host + NTRO_API_KEY.

ntro -c production tenant list

The hosted test instance at https://mcp.test.ntropii.com runs without auth — no API key needed for evaluation.A self-hosted MCP server reads the same ~/.ntro/config.toml when launched, so once ntro auth login has run, Claude Code (or any MCP client) authenticates with no extra config.For multi-environment self-host setups, pass --connection to the MCP server:

{
  "mcpServers": {
    "ntro": {
      "command": "ntro-mcp",
      "args": ["--connection", "production"]
    }
  }
}

Same precedence as the CLI: explicit constructor args > env vars > ~/.ntro/config.toml.

from ntro.workspace import Client

# Reads the default connection from config.toml
client = Client.from_config()

# Or pass a specific connection name
client = Client.from_config(connection="production")

# Or be explicit
client = Client(host="https://api.ntropii.com/v1", api_key="ntro_...")

Rotation

# 1. Mint a new key in the Ntropii web UI
# 2. Update the relevant connection
ntro auth login --name production
#    (overwrite when prompted; old key stays valid until you revoke it in the UI)

# 3. Revoke the old key in the UI

Because keys are tenant-scoped, rotation is a per-tenant operation. There is no concept of an organisation-wide rotation that revokes everything.

Don’t commit API keys to a runbook git repo. The repo is what gets uploaded to Ntropii Tenant on deploy — anything in the source tree ends up readable by your worker logs. Always read the key from ~/.ntro/config.toml (the SDK does this for you) or from a secrets manager at runtime.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

API keys & authentication

How keys are scoped

Generate a key

Where the key gets used

Rotation

What’s next

Ntro CLI reference

Wire MCP into your coding agent

​How keys are scoped

​Generate a key

​Where the key gets used

​Rotation

​What’s next

Ntro CLI reference

Wire MCP into your coding agent

How keys are scoped

Generate a key

Where the key gets used

Rotation

What’s next