Implementation: inc/Api/Agents.php, inc/Core/Auth/AgentAuthorize.php, inc/Core/Auth/AgentAuthCallback.php

Base URL: /wp-json/datamachine/v1

Overview

Agent endpoints manage agent records, user access grants, runtime bearer tokens, and the browser authorization flow used by external agent clients.

Authentication

There are three auth modes:

• Agent CRUD, access, and token management use the current WordPress user and Data Machine agent capabilities.
• GET /agents/me accepts either an agent bearer token context or a logged-in WordPress user.
• /agent/authorize and /agent/auth/callback are browser-facing flow endpoints with open REST permissions, then validate login cookies, nonces, redirect URIs, or callback payloads inside the handler.

Token values are sensitive. POST /agents/{agent}/tokens returns raw_token once; list endpoints return token metadata only.

Agent bearer-token requests populate PermissionHelper agent context. Token capabilities can be restricted by a capability ceiling, so a token can be narrower than the owning agent’s full Data Machine capability set.

Route Table

{agent} accepts an agent slug (sarai) or numeric agent ID (42). Slug routes are preferred.

Core Parameters

Agent CRUD

Access And Tokens

Browser Authorization

Response Shape

Most agent management responses use:

{
  "success": true,
  "data": {}
}

List responses return data as an array of agent or grant objects. Token ability responses return ability-native objects such as:

{
  "success": true,
  "token_id": 123,
  "raw_token": "datamachine_...",
  "token_prefix": "datamachine_abcd",
  "message": "Token created. Save it now - it cannot be retrieved again."
}

GET /agents/me returns identity metadata:

{
  "success": true,
  "data": {
    "agent_id": 2,
    "agent_slug": "sarai",
    "agent_name": "Sarai",
    "owner_id": 1,
    "site_url": "https://example.com",
    "site_name": "Example"
  }
}

Agent Usage Examples

Create a token for an external agent client:

curl -X POST https://example.com/wp-json/datamachine/v1/agents/sarai/tokens 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{"label":"kimaki-prod","expires_in":2592000}'

Use the returned bearer token to discover the active identity:

curl https://example.com/wp-json/datamachine/v1/agents/me 
  -H "Authorization: Bearer datamachine_..."

Start the browser authorization flow for a local client:

https://example.com/wp-json/datamachine/v1/agent/authorize?agent_slug=sarai&redirect_uri=http://localhost:31337/callback&label=local-cli&state=abc123