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

Control Plane

External control surfaces for enforcing and coordinating agent execution across environments.

External Control Plane

How MachineID’s external control plane coordinates execution authority, policy, and enforcement decisions across systems.

Open guide →
Runtime Enforcement

Runtime integration guides that show where to validate, how to fail closed, and how to wire enforcement cleanly into your system.

Python Runtime Guide

Python runtime enforcement patterns for agents and services: where to validate, how to gate work, and how to handle failures safely.

Open guide →
Node.js Runtime Guide

Node runtime enforcement patterns for APIs, workers, and tool servers: validate at execution boundaries and fail closed.

Open guide →
Frameworks

Guides and starter templates for common AI agent frameworks. Each guide follows the same enforcement pattern: register on startup, validate before work, and stop immediately when denied.

CrewAI Guide

Integrate MachineID runtime enforcement into CrewAI agents to gate execution reliably and keep fleets within plan limits.

Open guide →
LangChain Guide

Add MachineID validation checks around LangChain runs so agents fail closed and only execute when allowed.

Open guide →
LangGraph Guide

Apply MachineID enforcement to LangGraph workflows by validating at execution boundaries and blocking denied runs.

Open guide →
Swarm Guide

Add MachineID enforcement to Swarm-style multi-agent orchestration by validating at run entry, tool calls, handoffs, and side effects.

Open guide →
Hosted Agents

Guides for hosted agent runtimes where control must be applied at tool execution, resumes, and side effects.

OpenAI Agents Guide

External enforcement for OpenAI’s hosted agent runtime. Validate before tool calls, resumes, and irreversible side effects.

Open guide →
Starters / Templates

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

Framework Starters on GitHub

Copy-paste starters for CrewAI, LangChain, Swarm and plain Python. Includes wiring for register/validate and safe fail-closed behavior.

Open templates →
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

Practical integration patterns for production systems: execution boundaries, failure handling, and recommended placement for validate checks.

Where to validate and how to fail safely

A production-focused guide covering execution boundaries, fail-closed behavior, and recommended validate placement patterns.

Open guide →
Success