Configuration & Auth

Secure credential management

Your Niitaka API key grants full write access to your organisation's telemetry. Treat it like a database password — never hardcode it in source files or commit it to version control.

Local development — .env file

Use python-dotenv to load your key from a local .env file that is listed in .gitignore.

# .env  (never commit this file)
NIITAKA_API_KEY=nii_live_xxxxxxxxxxxx

from dotenv import load_dotenv
import os

load_dotenv()   # reads .env from the current working directory

import niitaka
niitaka.configure(api_key=os.getenv("NIITAKA_API_KEY"))

Docker and containers

Pass the key as an environment variable from the host — never bake it into the image.

# docker-compose.yml
services:
  agent:
    image: your-agent:latest
    environment:
      - NIITAKA_API_KEY=${NIITAKA_API_KEY}   # passed from host env, not hardcoded

CI/CD pipelines

Store the key as an encrypted secret in your CI provider and inject it at runtime. Example for GitHub Actions:

# .github/workflows/run-agent.yml
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python agents/my_agent/run.py
        env:
          NIITAKA_API_KEY: ${{ secrets.NIITAKA_API_KEY }}

For other CI platforms (GitLab, CircleCI, Buildkite) the pattern is the same: store the secret in the platform's secret store and reference it as an environment variable in your job definition.

API key management

Each Niitaka organisation has one API key. It is used by all SDK instances — agents, batch runners, and the CLI — that report to your org.

Where to find your key

Dashboard → Settings → API Keys. The key is only shown in full once on creation. Copy it to your secret store immediately — if you lose it you will need to rotate.

Rotating your key

Generate a new key before deleting the old one so there is no gap in coverage. The safe rotation sequence is:

# Step 1 — generate a new key in the dashboard
# Settings → API Keys → Generate new key

# Step 2 — deploy the new key to all agents
NIITAKA_API_KEY=nii_live_NEW_KEY python your_agent.py

# Step 3 — confirm sessions appear in the dashboard with the new key,
#          then delete the old key from Settings → API Keys

One key per org — what this means

The current model is one API key per organisation. All agents in an org share the same key, which means:

• A compromised key must be rotated for every agent simultaneously.
• You cannot grant a subset of agents access to a subset of data.
• Cost and telemetry from different teams or products is pooled under one org.

The recommended workaround for teams that need isolation today is to create a separate Niitaka organisation per department or environment and manage keys independently. Per-agent scoped keys and a project layer within an org are planned for a future release.

Dev, staging, and production

Running your agent in multiple environments (local, staging, production) without mixing their telemetry requires separate organisations — one per environment. Each org has its own API key, its own session data, and its own dashboard view.

Self-hosted deployment

By default, the SDK sends telemetry to https://api.niitaka.ai. If your data governance requirements prohibit sending data to a third-party, you can run the Niitaka backend in your own infrastructure and point the SDK at it.

Configuring the SDK for a self-hosted backend

Set api_url in niitaka.configure() to your self-hosted endpoint:

import niitaka

niitaka.configure(
    api_key=os.getenv("NIITAKA_API_KEY"),   # your own auth token
    api_url="https://niitaka.your-company.com",   # self-hosted backend URL
)

Architecture overview

A self-hosted Niitaka deployment runs three components. All communicate over HTTP and share a single Postgres database.

Next steps

• Core Concepts — sessions, events, policies, and runtime config.
• Runtime Config — push model and prompt changes to agents without redeployment.