Authentication

API keys authenticate both SDK connections and direct API requests. Get yours from API Keys in the dashboard. Keys are scoped to your organization and start with plx_.

In the SDK

Pass the key directly, or set PLEXUS_API_KEY as an environment variable and the SDK picks it up automatically:

import os
from plexus import Plexus

# Explicit
px = Plexus(api_key=os.environ.get("PLEXUS_API_KEY"), source_id="robot-01")

# Or set the env var and omit api_key entirely
# export PLEXUS_API_KEY=plx_...
px = Plexus(source_id="robot-01")

Both SDKs also read ~/.plexus/config.json, written by plexus init. Resolution order: explicit argument → PLEXUS_API_KEY → config file.

In API requests

Pass the key in the x-api-key header on every request:

curl https://api.plexus.company/v1/sources \
  -H "x-api-key: plx_..."

Key rotation

Zero-downtime rotation: create a new key, swap PLEXUS_API_KEY in your deployment environment, then delete the old key. Both keys work during the swap — deleting the old one cuts off anything still using it. Deletion takes effect within ~5 minutes (server-side key caches), so when security matters, rotate first and delete after.

Key scopes

Keys carry stored scopes: keys created in the dashboard or claimed by a coding agent get write; CLI-issued keys get read,write. Today only the write scope is enforced, and only at the gateway — the read API accepts any valid, billing-enabled key regardless of scope. Treat agent-claimed keys as ingest credentials by convention.

Payment required (402)

Nothing works until your org has a payment method on file: keys are created with access disabled, so the gateway rejects ingest and read endpoints return 402. Add a card in Settings → Subscription before anything works end-to-end.