Shipped: granular API keys for partner integrations

Granular API keys on a returns platform are scoped credentials that limit what a given integration can see or do, by tenant, by endpoint, and by action (read, write, or webhook subscription). areturnz shipped this capability so partners and brand teams can issue a key for order lookups without also handing over disposition controls or another tenant's evidence bundles. It is a small feature with a big blast radius: it changes how safely a partner can plug five different systems into one returns network.

Why this shipped now

Most of the partners running on areturnz are not single-tenant operations. A 3PL reselling returns processing under its own brand might have a warehouse management system, a customer support tool, a BI dashboard, and a finance system all needing different slices of return data. Before this release, an API key was mostly a blunt instrument: full account access or nothing. That worked fine at low volume. It stopped working once partners crossed a few thousand returns a month and started wiring up real internal tooling.

We cover the underlying architecture in multi-tenant webhook isolation done right, which is the sibling system to this change. Webhook isolation keeps event streams from leaking across tenants. Granular API keys do the same job for pull-based access: they make sure a support tool asking "what happened to parcel X" cannot also query another brand's inbound volume or trigger a disposition override.

What changed, concretely

Keys are now issued with three dimensions of scope:

Tenant scope

A key is bound to one tenant (or a defined set of tenants for node operators managing several brands). It cannot be reused, intentionally or by accident, to pull data outside that boundary. This matters most for partners running white-label operations across dozens of client accounts, where a leaked key used to mean a much bigger cleanup than it should.

Endpoint scope

Keys can be limited to specific resource types: return lookups, evidence bundle retrieval, disposition status, or webhook management. A finance integration pulling reconciliation data does not need write access to grading overrides, and now it does not get it by default.

Action scope

Within an allowed endpoint, a key can be read-only or read-write. Most integrations only ever need read access. Forcing write access to be a deliberate, separate grant cuts down on the number of systems that could theoretically change a disposition outcome.

How the scopes map to real workflows

What it protects against

Two failure modes drove this work. First, key sprawl: partners were generating one master key and pasting it into every internal tool, which meant rotating it after an employee left touched everything at once. Second, cross-tenant exposure risk in white-label setups, where a single overly broad key could technically reach data belonging to a different brand on the same node. Neither had caused a breach on our network, but both were the kind of latent risk that shows up eventually if you run enough tenants long enough. With 180K+ returns processed and growing partner counts, we would rather close the gap before it matters than explain it after.

This sits alongside the rest of the evidence and audit stack. Every return still carries its full photo record and disposition history, and every AI grading call still runs against the same 48 hour median cycle from inbound scan to disposition, with 99.6% AI-vs-operator match accuracy on grading decisions. Scoped keys do not change any of that. They just control who can ask for it and what they can do once they have the answer.

Rollout details partners should know

Existing keys were not silently downgraded. Legacy full-access keys continue to work, but the dashboard now flags them and recommends splitting them into scoped equivalents. New keys default to read-only, single-tenant, single-endpoint unless a broader scope is explicitly requested and confirmed. Key creation, rotation, and revocation events are logged the same way disposition overrides are logged, so there is a record of who issued what and when.

If you are running or planning a multi-tenant setup, this is also a good moment to revisit per-tenant reporting, which uses the same isolation principles to keep partner dashboards accurate without exposing data across brands.

Frequently asked questions

Do I need to reissue all my existing API keys?

No. Existing keys keep working. The dashboard will show a recommendation to migrate broad keys to scoped ones, and most partners do this gradually as they touch each integration rather than all at once.

Can a single key span multiple tenants?

Only for node operators managing multiple brand tenants under one partner account, and even then each tenant's data stays isolated within that key's permitted scope. A standard brand or retailer account issues single-tenant keys.

Does scoping a key slow down integration work?

It adds one extra step at setup (choosing scope), but it removes the back-and-forth that used to happen when a security or compliance review flagged an overly broad key later. Most partners find it faster end to end.

Where do granular API keys fit with webhook isolation?

They are companion features. Webhook isolation controls what event data gets pushed to a tenant's endpoints, while granular API keys control what a credential can pull or write on request. Together they cover both push and pull access paths.

Is this feature available on all pricing tiers?

Scoped key creation is available across the network. Details on tier-specific limits and volume are on the pricing page. For partner-specific setups, see how partners use areturnz.

Want to see the full list of shipped changes and how they connect to the bigger platform story? Visit the product updates hub, or if you are setting up a new integration and want scoping recommendations for your specific tenant structure, contact areturnz and we will walk through it with you.

Related reading: Shipped: Real-Time Ops Notifications on the Receiving Line

Related reading: Shipped: package lookup across the network