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

# API keys & authentication

> Mint, scope, and rotate the API key your CLI, MCP server, and SDK use to reach Ntropii Workspace.

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

```bash theme={null}
ntro auth login
```

Walks you through:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Enter the host">
    `https://api.ntropii.com/v1` for production.
  </Step>

  <Step title="Paste the API key">
    You generate the key in the Ntropii web UI under Settings → API keys. The CLI does not mint keys directly.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

Verify the key works:

```bash theme={null}
ntro auth whoami
# → identity, organisation, accessible tenants
```

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

```bash theme={null}
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:

<Tabs>
  <Tab title="CLI">
    Picked up automatically from `~/.ntro/config.toml` based on the active connection. Override with `--host` + `NTRO_API_KEY`.

    ```bash theme={null}
    ntro -c production tenant list
    ```
  </Tab>

  <Tab title="MCP server">
    The [hosted test instance](/tooling/mcp-server#quick-start--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:

    ```json theme={null}
    {
      "mcpServers": {
        "ntro": {
          "command": "ntro-mcp",
          "args": ["--connection", "production"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="SDK (Python)">
    Same precedence as the CLI: explicit constructor args > env vars > `~/.ntro/config.toml`.

    ```python theme={null}
    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_...")
    ```
  </Tab>
</Tabs>

## Rotation

```bash theme={null}
# 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.

<Warning>
  **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.
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Ntro CLI reference" icon="terminal" href="/tooling/ntro-cli">
    Discover each command, flag, and example to use on Ntropii.
  </Card>

  <Card title="Wire MCP into your coding agent" icon="robot" href="/tooling/coding-agents/overview">
    Give Claude Code or Copilot Studio access to Ntropii.
  </Card>
</CardGroup>