Manage your agents

See every agent (agt_*) you have created, inspect one, rename it, or revoke it when it is done. For how agents fit with keys and limits, read the Agents overview.

List your agents

List every agent on your account with GET /agents.

from naturalpay import Natural

client = Natural()
agents = client.agents.list()

import Natural from "@naturalpay/sdk";

const client = new Natural();
const agents = await client.agents.list();

natural agents list

List my agents.

curl https://api.natural.com/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY"

The response carries each agent with its handle, status, and limits:

Inspect one agent

Inspect one agent by ID with GET /agents/{agentId}.

agent = client.agents.get("agt_019cd1798d637a4da75dce386343931d")

const agent = await client.agents.get({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
});

natural agents get --agent-id agt_019cd1798d637a4da75dce386343931d

Show me my Procurement Agent.

curl https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY"

The response carries the agent:

Rename an agent

Rename an agent, change its description, or adjust its limits, with PATCH /agents/{agentId}. Set limits from a user session or party API key; an agent key cannot change its own limits. limits: null clears them.

import uuid

agent = client.agents.update(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
    name="Procurement Agent v2.1",
    description="Autonomous agent that pays contractors",
)

const agent = await client.agents.update({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
  name: "Procurement Agent v2.1",
  description: "Autonomous agent that pays contractors",
});

natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
  --name "Procurement Agent v2.1" \
  --description "Autonomous agent that pays contractors" \
  --idempotency-key "$(uuidgen)"

curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "name": "Procurement Agent v2.1",
        "description": "Autonomous agent that pays contractors"
      }
    }
  }'

The response carries the updated agent:

Revoke an agent

Revoke an agent with DELETE /agents/{agentId}. Its status becomes REVOKED and it stops moving money at once, but the record stays readable so its history survives. Revoking also revokes every customer authorization the agent holds and cancels its pending invitations.

import uuid

client.agents.remove(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
)

await client.agents.remove({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
});

natural agents remove --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)"

curl -X DELETE https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The response carries the agent with status REVOKED:

Manage agent keys

An agent key (ak_ntl_*) is a credential bound to one agent. Your dashboard lists keys on the agent detail page; over the API, use the agent-keys endpoints below. Issue a new key when you create an agent.

List keys

There is no get-by-id endpoint. List keys with GET /agent-keys (scope api_keys.read), optionally filtered by agentId.

keys = client.agent_keys.list(agent_id="agt_019cd1798d637a4da75dce386343931d")

const keys = await client.agentKeys.list({ agentId: "agt_019cd1798d637a4da75dce386343931d" });

natural agent-keys list --agent-id agt_019cd1798d637a4da75dce386343931d

curl "https://api.natural.com/agent-keys?agentId=agt_019cd1798d637a4da75dce386343931d" \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN"

Rotate a key

Rotate with POST /agent-keys/{keyId}/rotate to issue a fresh secret on the same agent. Set a grace period so running workloads can pick up the new key before the old one stops working. The new secret is again shown once. Rotate and revoke from a user session, as when issuing; $NATURAL_USER_TOKEN in the cURL examples is that session credential, the same one natural login stores for the CLI. expiresInSeconds runs from 0 (immediate) to 86400.

import uuid

rotated = client.agent_keys.rotate(
    key_id="agk_019cd1798d6d1353281cf4cdf5d20c8d",
    expires_in_seconds=86400,
    idempotency_key=str(uuid.uuid4()),
)

const rotated = await client.agentKeys.rotate({
  keyId: "agk_019cd1798d6d1353281cf4cdf5d20c8d",
  expiresInSeconds: 86400,
  idempotencyKey: crypto.randomUUID(),
});

natural agent-keys rotate \
  --key-id agk_019cd1798d6d1353281cf4cdf5d20c8d \
  --expires-in-seconds 86400 \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/agent-keys/agk_019cd1798d6d1353281cf4cdf5d20c8d/rotate \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "expiresInSeconds": 86400 } } }'

Revoke a key

Revoke with DELETE /agent-keys/{keyId} to invalidate a key immediately. This cannot be undone, and other keys on the same agent keep working. Use it when a secret leaks or you retire one credential without revoking the agent.

import uuid

client.agent_keys.revoke(
    key_id="agk_019cd1798d6d1353281cf4cdf5d20c8d",
    idempotency_key=str(uuid.uuid4()),
)

await client.agentKeys.revoke({
  keyId: "agk_019cd1798d6d1353281cf4cdf5d20c8d",
  idempotencyKey: crypto.randomUUID(),
});

natural agent-keys revoke \
  --key-id agk_019cd1798d6d1353281cf4cdf5d20c8d \
  --idempotency-key "$(uuidgen)"

curl -X DELETE https://api.natural.com/agent-keys/agk_019cd1798d6d1353281cf4cdf5d20c8d \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Overview

Common use cases

Products

Guides

List your agents

Inspect one agent

Rename an agent

Revoke an agent

Manage agent keys

List keys

Rotate a key

Revoke a key

​List your agents

​Inspect one agent

​Rename an agent

​Revoke an agent

​Manage agent keys

​List keys

​Rotate a key

​Revoke a key

List your agents

Inspect one agent

Rename an agent

Revoke an agent

Manage agent keys

List keys

Rotate a key

Revoke a key