Manage customer access

See which customers your agents act for, inspect what each one granted, and revoke an agent or a pending invitation whenever you need to. For the connection model, read the Customers overview.

See who your agents act for

Your customers list holds every customer who has connected an agent to you. Each entry’s id is the party ID (pty_*) you pass as customerPartyId when you act for them, and each entry shows the agents (agt_*) acting for that customer, with the permissions and limits (perTransaction, plus any perDay or perMonth cap you set on the agent) in force. Read it with GET /customers.

from naturalpay import Natural

client = Natural()
customers = client.customers.list()

for customer in customers.data:
    print(customer.id, customer.attributes.name)

import Natural from "@naturalpay/sdk";

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

for (const customer of customers.data) {
  console.log(customer.id, customer.attributes.name);
}

natural customers list

List my active customers and the agents acting for them.

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

The response carries each customer with the agents acting for them: Filter by status: active (default) for every non-revoked connection, revoked for customers whose access ended, or all for both. Pending invitations are on a separate list, below. A pending invitation stays on your invitations list until the customer accepts, you revoke it, it expires, or another invitation connects the same agent and customer.

Inspect one customer

Read a single customer with GET /customers/{customerId} to see exactly which agents, permissions, and limits are in force before you change anything. The customerId is that customer’s party ID. A disconnected customer is still readable; its delegation.status is REVOKED.

customer = client.customers.get("pty_019cd1798d627ad9bc302511c4f2c115")

print(customer.data.id, customer.data.attributes.agents)

const customer = await client.customers.get({
  customerId: "pty_019cd1798d627ad9bc302511c4f2c115",
});

console.log(customer.data.id, customer.data.attributes.agents);

natural customers get --customer-id pty_019cd1798d627ad9bc302511c4f2c115

Show me customer pty_019cd1798d627ad9bc302511c4f2c115 and what my agents can do for them.

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

The response carries the customer:

See pending invitations

Invitations you have sent but nobody has accepted yet live on a separate list. Read it with GET /customers/invitations to confirm what is still open before you revoke.

pending = client.customers.list_invitations()

for invitation in pending.data:
    print(invitation.attributes.email, invitation.attributes.status)

const pending = await client.customers.listInvitations();

for (const invitation of pending.data) {
  console.log(invitation.attributes.email, invitation.attributes.status);
}

natural customers list-invitations

Show my pending customer invitations.

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

The response carries one entry per recipient: Each entry’s id is the recipient’s email, and party is null until they have signed up. Each recipient groups its agentInvitations, one adi_* per agent you invited them to. You revoke by that invitationId. You can invite more than one person at a customer before they connect. Once Natural identifies the recipient’s customer, the invitation stays bound to that customer even if the contact later joins another party. When any one of those invitations connects an agent, Natural cancels the other pending invitations for that agent and customer with cancelReason: CONNECTION_ESTABLISHED. They stay canceled if access is later revoked, so reconnecting requires a fresh invitation. While the connection is active, new invitations for that agent and customer are skipped, no invitation email is sent, and the existing connection is returned in meta.alreadyConnected.

Revoke a pending invitation

Cancel an invitation the recipient has not accepted with DELETE /customers/invitations/{invitationId}, and they can no longer accept it. Revoking an invitation needs delegation_invitations.delete on your key; revoking an agent or disconnecting a customer needs delegations.delete, which includes it.

client.customers.revoke_invitation("adi_019cd1798d96adc082e235b426d4e04c")

await client.customers.revokeInvitation({
  invitationId: "adi_019cd1798d96adc082e235b426d4e04c",
});

natural customers revoke-invitation --invitation-id adi_019cd1798d96adc082e235b426d4e04c

curl -X DELETE https://api.natural.com/customers/invitations/adi_019cd1798d96adc082e235b426d4e04c \
  -H "Authorization: Bearer $NATURAL_API_KEY"

The invitation’s status becomes CANCELED with a cancelReason of DEVELOPER_REVOKED. Revoking an invitation that is no longer PENDING returns 409; treat that as already done.

Revoke an agent’s access

Once a customer has accepted, you revoke per agent. DELETE /customers/{customerId}/agents/{agentId} strips one agent’s authority over that customer immediately. customerId is the customer’s party ID, and agentId is the agent you are pulling.

client.customers.revoke_agent(
    "pty_019cd1798d627ad9bc302511c4f2c115",
    "agt_019cd1798d637a4da75dce386343931d",
)

await client.customers.revokeAgent({
  customerId: "pty_019cd1798d627ad9bc302511c4f2c115",
  agentId: "agt_019cd1798d637a4da75dce386343931d",
});

natural customers revoke-agent \
  --customer-id pty_019cd1798d627ad9bc302511c4f2c115 \
  --agent-id agt_019cd1798d637a4da75dce386343931d

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

Removing the last agent leaves the customer connection active with no agent grants. This preserves connection-level consent, including subscribed lifecycle webhooks, until either party explicitly disconnects. Revoking an agent that is already gone returns 404; treat that as already done.

Disconnect the customer

Use DELETE /customers/{customerId} to end the whole connection at once from the developer side. The customer can also disconnect from their dashboard. Send an Idempotency-Key; the request is rejected without it. Natural atomically revokes every active agent grant and the customer relationship, so no agent remains authorized if the request succeeds. Retry with the same Idempotency-Key to get the same response. If the response says access cleanup is still pending, retry the request. Disconnecting stops new activity and new connected webhook deliveries at once. Events already delivered stay readable; undelivered ones are not exposed.

Overview

Common use cases

Products

Guides

See who your agents act for

Inspect one customer

See pending invitations

Revoke a pending invitation

Revoke an agent’s access

Disconnect the customer

​See who your agents act for

​Inspect one customer

​See pending invitations

​Revoke a pending invitation

​Revoke an agent’s access

​Disconnect the customer

See who your agents act for

Inspect one customer

See pending invitations

Revoke a pending invitation

Revoke an agent’s access

Disconnect the customer