Documentation

Integration guide, client libraries, and API reference.

Need a key? Generate one on the Home page or Console.
Quickstart

The API is simple enough to use with raw HTTP calls. Replace YOUR_ORG_KEY with your actual org key.

1. Register (On Startup)
curl -X POST https://machineid.io/api/v1/devices/register \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "deviceId": "agent-01" }'
2. Validate (Before Work)
curl -X POST "https://machineid.io/api/v1/devices/validate" \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{"deviceId":"agent-01"}'
Python & SDKs

Official Python client designed for agents and automation. Returns raw API JSON.

Install
pip install machineid-io
(Note: If your system Python blocks pip installs, use a virtual environment.)
View source on GitHub →
Prerequisite
Set your org key as an environment variable: 
export MACHINEID_ORG_KEY=org_your_key_here
Usage
from machineid_io import MachineID

# Set MACHINEID_ORG_KEY in your env
client = MachineID.from_env()
device_id = "agent-01"

# Register (idempotent)
client.register(device_id)

# Validate before work
val = client.validate(device_id)
if not val.get("allowed"):
    raise SystemExit("Device blocked")
Templates (Optional Starters)

Pre-wired examples showing how to integrate MachineID into common AI agent frameworks.

Framework Examples
CrewAI · LangChain · Swarm · Plain Python
View all templates on GitHub →
Core Concepts
Org Key

A single secret key representing your organization. All devices share this key. It starts with org_. Pass it in the x-org-key header.

Plan Limits

Enforcement is server-side. Free: 3 devices. Pro: 25. Scale: 250. Max: 1,000. When you hit a plan limit, registration is blocked with HTTP 403 and status: "blocked", error: "device_limit_reached".

Device Lifecycle
1

Get Org Key

Generate one on the Home page or via the Console (Dashboard).

2

Register (On Startup)

Safe to call on every boot. Returns status: "ok" or status: "exists".

3

Validate (Before Work)

Before running a task, call /validate. Gate execution on allowed.

4

Manage Fleet (Optional)

Use the Console (Dashboard) or the management endpoints to list, revoke, restore, and remove devices.

API Reference
POST /api/v1/devices/register

Idempotent registration. Safe to call every time your agent starts.

curl -X POST https://machineid.io/api/v1/devices/register \\
-H "Content-Type: application/json" \\
-H "x-org-key: YOUR_ORG_KEY" \\
-d '{ "deviceId": "agent-01" }'
POST /api/v1/devices/validate

Runtime authority check. You must stop execution immediately when allowed is false.

Important notes
  • Org execution overrides everything. If org execution is disabled, validate returns ORG_DISABLED.
  • Fail-closed availability. If MachineID cannot complete an authoritative decision, validate returns SYSTEM_UNAVAILABLE and denies.

Client guidance: call validate before work. If allowed is false, exit. If code is SYSTEM_UNAVAILABLE, you may optionally retry with backoff based on your client’s tolerance for delay. 

curl -X POST https://machineid.io/api/v1/devices/validate \\
-H "Content-Type: application/json" \\
-H "x-org-key: YOUR_ORG_KEY" \\
-d '{"deviceId":"agent-01"}'

Decision Codes

Every validate response includes a stable code and a request_id for debugging and correlation.

  • ALLOW — Execution allowed.
  • ORG_DISABLED — Org execution is disabled; overrides all device/plan checks.
  • SYSTEM_UNAVAILABLE — MachineID could not complete an authoritative decision; fail-closed deny.
  • PLAN_FROZEN — Org is frozen.
  • ENTITLEMENT_EXPIRED — Plan entitlement is not active.
  • DEVICE_REVOKED — Device revoked.
  • DEVICE_NOT_FOUND — Device not registered.
  • ORG_NOT_FOUND — Org not found.
  • INVALID_ORG_KEY — Bad or missing org key.
  • INVALID_DEVICE_ID — Invalid device ID.

Use request_id to correlate client logs with MachineID decisions.

GET /api/v1/devices/list

Returns all devices for the org.

curl -X GET https://machineid.io/api/v1/devices/list \\
-H "x-org-key: YOUR_ORG_KEY"
POST /api/v1/devices/revoke

Blocks a device. Effective on next validation check.

curl -X POST https://machineid.io/api/v1/devices/revoke \\
-H "Content-Type: application/json" \\
-H "x-org-key: YOUR_ORG_KEY" \\
-d '{ "deviceId": "agent-01" }'
POST /api/v1/devices/unrevoke

Explicitly re-grants execution authority to a device.

curl -X POST https://machineid.io/api/v1/devices/unrevoke \\
-H "Content-Type: application/json" \\
-H "x-org-key: YOUR_ORG_KEY" \\
-d '{ "deviceId": "agent-01" }'
POST /api/v1/devices/revoke_batch

Bulk revoke devices. You may revoke an explicit list of device IDs or revoke all currently-active devices. Selected mode is idempotent (already revoked devices are no-ops). Invalid IDs are reported per-item.

Selected Devices
curl -X POST https://machineid.io/api/v1/devices/revoke_batch \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "deviceIds": ["agent-01", "agent-02", "agent-03"] }'
Notes: deviceIds max is 500 (valid IDs). IDs are de-duped. Unknown IDs return status: "not_found" in results.
All Active Devices
curl -X POST https://machineid.io/api/v1/devices/revoke_batch \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "scope": "all_active" }'
Returns revokedCount for the number of active devices revoked in this call.
POST /api/v1/devices/unrevoke_batch

Bulk unrevoke (restore) revoked devices. Restore is capacity-aware: restores up to (limit - activeCount). Restore All uses newest-revoked-first ordering. Selected restore may be partial when at cap.

Selected Devices
curl -X POST https://machineid.io/api/v1/devices/unrevoke_batch \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "deviceIds": ["agent-01", "agent-02", "agent-03"] }'
Notes: if you are at plan capacity, revoked candidates are returned as status: "blocked", error: "device_limit_reached". Invalid IDs are reported per-item.
Restore All Revoked (Up To Capacity)
curl -X POST https://machineid.io/api/v1/devices/unrevoke_batch \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "scope": "all_revoked" }'
Returns unrevokedCount and a unrevokedSample (up to 25 device IDs). When nothing is restored, reason is "at_cap" or "none_revoked".
POST /api/v1/devices/remove

Hard Delete. Permanently removes the device record.

curl -X POST https://machineid.io/api/v1/devices/remove \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "deviceId": "agent-01" }'
GET /api/v1/usage

Returns current plan tier, device count, and limit.

curl -X GET https://machineid.io/api/v1/usage \\
  -H "x-org-key: YOUR_ORG_KEY"
POST /api/v1/billing/checkout

Generates a Stripe Checkout URL to upgrade the org.

curl -X POST https://machineid.io/api/v1/billing/checkout \\
  -H "Content-Type: application/json" \\
  -H "x-org-key: YOUR_ORG_KEY" \\
  -d '{ "plan": "scale" }'
Automation & Agents
Designed for scripts, services, and AI tools
The API shapes are intentionally small and predictable so automation stays safe and boring.

Gate execution

Always gate on allowed from /devices/validate.

Idempotent startup

/devices/register is safe to call on every boot.

Explicit enforcement

When capacity is full, registration is blocked with HTTP 403.

Retry responsibly

On transient network failures, retry with backoff. If validate returns SYSTEM_UNAVAILABLE, treat it as a deny unless you explicitly choose to retry.

Error Patterns
Observed responses
  • status: "ok" — Success.
  • status: "exists" — Register called again (idempotent).
  • status: "blocked", error: "device_limit_reached" — Per-item blocked by plan cap (request succeeds).
  • status: "revoked" — Device is blocked.
  • missing_params — Malformed request.
Implementation Guide
Where to validate and how to fail safely
Practical integration patterns for production systems: execution boundaries, failure handling, and recommended placement for validate checks.
Open guide →
Success