Create an agent

An agent is an actor that moves money for you. Every payment, request, deposit, and withdrawal is attributed to its ID, so create one before you move any money. Create an agent with POST /agents.

import uuid
from naturalpay import Natural
from naturalpay.agents import CreateAgentsRequestLimits

client = Natural()
agent = client.agents.create(
    name="Procurement Agent",
    slug="procurementagent",
    description="Buys supplies",
    limits=CreateAgentsRequestLimits(per_transaction=100_000),
    idempotency_key=str(uuid.uuid4()),
)

agent_id = agent.data.id

import Natural from "@naturalpay/sdk";

const client = new Natural();
const agent = await client.agents.create({
  name: "Procurement Agent",
  slug: "procurementagent",
  description: "Buys supplies",
  limits: { perTransaction: 100_000 },
  idempotencyKey: crypto.randomUUID(),
});

const agentId = agent.data.id;

natural agents create --json '{
  "name": "Procurement Agent",
  "slug": "procurementagent",
  "description": "Buys supplies",
  "limits": { "perTransaction": 100000 }
}' --idempotency-key "$(uuidgen)"

Create an agent called "Procurement Agent" with slug procurementagent for buying supplies, with a $1,000 per-transaction limit.

curl -X POST https://api.natural.com/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "name": "Procurement Agent",
        "slug": "procurementagent",
        "description": "Buys supplies",
        "limits": { "perTransaction": 100000 }
      }
    }
  }'

Store the returned agent ID (agt_*) and pass it whenever this agent moves money, so Natural attributes the money movement to it.

Issue a key

Creating an agent returns its ID, not a credential. Issue a key next so your runtime can authenticate as that agent with ak_ntl_*. The dashboard runs POST /agents and POST /agent-keys back to back; over the API you do the same.

key = client.agent_keys.create(
    data={
        "attributes": {},
        "relationships": {
            "agent": {"data": {"type": "agent", "id": agent_id}},
        },
    },
)
print(key.data.attributes.agent_key)

const key = await client.agentKeys.create({
  data: {
    attributes: {},
    relationships: {
      agent: { data: { type: "agent", id: agentId } },
    },
  },
});
console.log(key.data.attributes.agentKey);

natural agent-keys create --agent-id agt_019cd1798d637a4da75dce386343931d

curl -X POST https://api.natural.com/agent-keys \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {},
      "relationships": {
        "agent": {
          "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" }
        }
      }
    }
  }'

Issue keys from a user session only, not from a party API key. The full secret is returned once, so store it in your secrets manager immediately. Afterward you can see only its prefix. To list, rotate, or revoke keys on an existing agent, see Manage your agents.

Overview

Common use cases

Products

Guides

Issue a key

​Issue a key

Issue a key