Agents API

POST /api/agents

Create a new agent.

Auth: Admin

Request:

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -u admin@example.com:changeme \
  -d '{
    "name": "my-agent",
    "scopes": ["read", "write"],
    "organization_id": "org_123",
    "expires_in": 7776000
  }'

Response (201):

{
  "agent": {
    "id": "550e8400-...",
    "name": "my-agent",
    "client_id": "cid_abc123...",
    "scopes": ["read", "write"],
    "is_active": true,
    "created_at": "2026-03-01T12:00:00Z"
  },
  "client_id": "cid_abc123...",
  "client_secret": "cs_secret..."
}

---

GET /api/agents

List all agents.

Auth: Admin

Response (200):

{
  "agents": [
    {
      "id": "550e8400-...",
      "name": "my-agent",
      "client_id": "cid_abc123...",
      "scopes": ["read", "write"],
      "is_active": true,
      "token_count": 5
    }
  ]
}

---

GET /api/agents/:id

Get a single agent.

Auth: Admin

Response (200):

{
  "agent": {
    "id": "550e8400-...",
    "name": "my-agent",
    "client_id": "cid_abc123...",
    "scopes": ["read", "write"],
    "is_active": true,
    "token_count": 5,
    "refresh_count": 2,
    "last_activity_at": "2026-03-01T12:00:00Z"
  }
}

---

DELETE /api/agents/:id

Delete an agent.

Auth: Admin

Response: 204 No Content

---

POST /api/agents/:id

Rotate agent credentials.

Auth: Admin

Request:

curl -X POST http://localhost:8080/api/agents/AGENT_ID \
  -H "Content-Type: application/json" \
  -u admin@example.com:changeme \
  -d '{"action": "rotate"}'

Response (200):

{
  "client_secret": "cs_new_secret..."
}

---

GET /api/agents/me

Get authenticated agent's profile.

Auth: Bearer Token

Response (200):

{
  "agent": {
    "id": "550e8400-...",
    "name": "my-agent",
    "client_id": "cid_abc123...",
    "scopes": ["read", "write"],
    "is_active": true
  }
}

---

GET /api/agents/me/usage

Get agent's usage statistics.

Auth: Bearer Token

Response (200):

{
  "token_count": 5,
  "refresh_count": 2,
  "last_activity_at": "2026-03-01T12:00:00Z",
  "rotation_history": [
    {
      "rotated_at": "2026-02-15T08:00:00Z"
    }
  ]
}

---

POST /api/agents/me/rotate

Rotate own credentials.

Auth: Bearer Token

Response (200):

{
  "client_secret": "cs_new_secret..."
}

---

POST /api/agents/me/deactivate

Deactivate self.

Auth: Bearer Token

Response (200):

{
  "message": "agent deactivated successfully"
}

---

DELETE /api/agents/me/delete

Delete self.

Auth: Bearer Token

Response: 204 No Content