Skip to main content

Native Auth API Key Playbook

Use this playbook to exercise the execution API in native/test mode—useful when you need to seed telemetry or debug API key behaviour locally.

1. Start the Server in Native Mode​

AUTH_PROVIDER=native \
ENABLE_TEST_MODE=true \
DEPLOYMENT_MODE=test \
API_PORT=8030 \
make dev

During startup the logs print a one-time admin key (look for ADMIN API KEY (SAVE THIS SECURELY - SHOWN ONLY ONCE)). Save it for later steps.

Tip: Guarantee a known admin key by launching Uvicorn manually first:

ADMIN_API_KEY=ak_local_admin \
ADMIN_TENANT_ID=tenant-dev \
AUTH_PROVIDER=native \
ENABLE_TEST_MODE=true \
DEPLOYMENT_MODE=test \
WRITE_ADMIN_KEY_FILE=true \
python3 -m uvicorn src.api.main:app --host 0.0.0.0 --port 8030

Subsequent runs can rely on ak_local_admin with tenant tenant-dev.

2. Mint a Service Key​

Create keys through the HTTP API so they register in the in-memory store:

ADMIN_KEY=<admin key>

curl -sS http://127.0.0.1:8030/api/v1/auth/v2/api-keys \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{
        "name": "telemetry-seed",
        "scopes": ["functions:execute"],
        "expires_days": 7
      }'

Store the key value immediately—the API returns it once.

3. Exercise the Execution Endpoint​

API_KEY=<service key>
RUFID=rufid:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
NAMESPACE=public

for i in {1..4}; do
  curl -sS -X POST http://127.0.0.1:8030/api/v1/execution/execute \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $API_KEY" \
    -d "{\
          \"rufid\": \"${RUFID}\",\
          \"function_name\": \"telemetry-demo\",\
          \"namespace\": \"${NAMESPACE}\",\
          \"source_code\": \"def handler(event, context):\\n    return {\\\"ok\\\": True, \\\"sample\\\": context.namespace}\",\
          \"input_data\": {\"ping\": \"pong\"}\
        }"
  echo
done

Expect JSON payloads with execution_id and timing metrics (no 401/404).

4. Export Telemetry Snapshot​

PYTHONPATH="$(pwd)" TELEMETRY_ENV_PATH="$(pwd)/.env.development" \
  python3 -c "from src.observability.api_telemetry_export import run_export; run_export(minutes=60)"

The exporter writes data/analytics/api_function_daily_snapshot.jsonl and upserts warehouse rows if ANALYTICS_DATABASE_URL is configured.

5. Cleanup​

  1. Stop the native dev server (Ctrl+C).
  2. Restore .env.development defaults (AUTH_PROVIDER=clerk, ENABLE_TEST_MODE=false, DEPLOYMENT_MODE=development).
  3. Restart make dev normally.

Future Enhancements​

  • Consolidate provider routers under /api/v1/auth
  • Persist dev-mode keys to the database
  • Add scripts/monitoring/api_key_smoke.sh for one-command runs
  • Encode native overrides in make native-dev
  • Seed namespaces (e.g., tenant-dev/sandbox) automatically

Track progress in dev_process/tracking/issues/FN-056-api-telemetry-baseline.md.