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.

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.

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"

If the agent you remove is the last one acting for that customer, the whole customer resource comes back with meta.deleted: true, and the relationship is over. Revocation is idempotent: pulling an agent that is already gone changes nothing, so it is safe to retry.

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

​See who your agents act for

​Inspect one customer

​See pending invitations

​Revoke a pending invitation

​Revoke an agent’s access

See who your agents act for

Inspect one customer

See pending invitations

Revoke a pending invitation

Revoke an agent’s access