Open app

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")

If a machine has a key saved in ~/.plexus/config.json, the SDK reads it from there. Resolution order: explicit argument → PLEXUS_API_KEY → config file.

Setting up with a coding agent? The agent creates the key for you and saves it as PLEXUS_API_KEY. See the Quickstart.

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. A key created on the API Keys page, or by your coding agent during set-up, gets write: it can send data. The write scope is enforced at the gateway; the read API accepts any valid, billing-enabled key regardless of scope.

dashboards lets a key read, create, change and delete dashboards. Keys without it get 403 on every dashboard endpoint, so a key on a device can't touch your dashboards. Leave Manage dashboards off for keys that go on hardware.

commands lets devices that connect with the key offer commands you run from Plexus. Tick Receive commands when creating the key. See Commands.

Payment required (402)

The Free plan needs no card: its keys work for ingest and reads. Pro never turns off your keys because of the bill; it emails you instead. An org on an older plan can have its API access turned off — for example, no payment method on file or a spend cap reached. While it is off, the read API answers 402, and sending answers 401 (the SDK raises AuthenticationError: Invalid API key). Fix it in Settings → Subscription.

A different 402 comes from the app at app.plexus.company: a Free org calling something that needs Pro, such as monitors or sharing, gets 402 with the error UPGRADE_REQUIRED.

Free has its own limits, such as the device cap and no live streaming. See Plans and limits.