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.

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 you pass as customerPartyId when you act for them, and each entry shows the agents acting for that customer, with the permissions and perTransaction limit 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"

Filter by status: active for accepted access, pending for unaccepted invitations, or all for both. 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.

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

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

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

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

natural customers get --customer-id pty_019cd1798d617f65a79cb965dda9eac3

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

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

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 listInvitations

Show my pending customer invitations.

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

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 organization. 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.

client.customers.revoke_invitation("adi_550e8400e29b41d4a716446655440000")

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

natural customers revokeInvitation --invitation-id adi_550e8400e29b41d4a716446655440000

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

The invitation’s status becomes CANCELED with a cancelReason of DEVELOPER_REVOKED. Revoking an already-canceled or already-accepted invitation is a no-op, so retries are safe.

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_019cd1798d617f65a79cb965dda9eac3",
    "agt_019cd1798d637a4da75dce386343931d",
)

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

natural customers revokeAgent \
  --customer-id pty_019cd1798d617f65a79cb965dda9eac3 \
  --agent-id agt_019cd1798d637a4da75dce386343931d

curl -X DELETE https://api.natural.com/customers/pty_019cd1798d617f65a79cb965dda9eac3/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. Revocation is idempotent: pulling an agent that is already gone changes nothing, so it is safe to retry.

Disconnect the customer

Use DELETE /customers/{customerId} to end the whole connection at once from the developer side. Natural’s connection model also permits the customer to disconnect through a customer-facing surface. Natural atomically revokes every active agent grant and the customer relationship, so no agent remains authorized if the request succeeds. A retry returns the already-revoked state and does not emit duplicate revocation events. Disconnect stops new customer activity and new sources: ["connected"] webhook deliveries immediately. Events already delivered under the former connection remain available in event history as audit evidence; events that were never delivered are not exposed through the former connection.

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