API key scopes

Every Flint API key holds a set of scopes, and each endpoint checks for the scopes it needs. A key that lacks them gets 403 INSUFFICIENT_SCOPE. Grant each key the narrowest set its job needs.

To send a key, choose between test and live keys, or create and revoke keys over the API, see Authentication. For expiry, rotation, and leak response, see Key security.

Scope catalog#

The table is generated from the same catalog used by API key validation and the dashboard pickers.

How scopes are evaluated#

A matching write scope satisfies its read scope. For example, commerce.orders.write satisfies a route requiring commerce.orders.read. A write scope does not satisfy reads for a sibling resource, and unqualified scopes do not imply qualified permissions such as commerce.refunds.tax_overrides.write.

all is reserved for trusted internal keys and cannot be granted to an external API key.

Returns use commerce.returns.write for requests and decisions, commerce.returns.operations.write for receiving and inspection work, and commerce.returns.resolutions.write for refunds, credits, and exchanges. POST /v1/returns/{return_id}/process requires all three. Gift card notifications and code replacement both use commerce.gift_cards.secrets.write.

Creating, committing, consuming, and releasing inventory reservations requires commerce.inventory.write. Managing a Location's inventory settings requires commerce.inventory_locations.write, so you can grant stock operations without permission to change where orders ship from or buyers pick up.

Payment scopes follow ownership, not resource type#

A payment intent that belongs to an order is authorized by the order's scopes, not by payments.payment_intents.write. The route you call decides the scope you need.

A key holding only payments.payment_intents.write receives INSUFFICIENT_SCOPE on every order-scoped payment route. The error's scope_requirement and missing_scopes fields name the exact missing authority.