API key scopes for AI agents: separate browsing from buying

A prompt cannot restrict an API key

Consider an agent whose job is to compare two products. Its tools need catalog information. Giving that process a general write key also gives it authority it does not need for the comparison. A prompt saying “only browse” leaves that authority available to any code holding the credential.

Enforce permissions where requests enter the service. The OWASP authorization guidance recommends granting the minimum necessary permissions and checking them on every request. For an agent integration, apply that principle to the tool executor as well as the API credential.

What OrderCore scopes actually mean

On authenticated routes protected by OrderCore's scope middleware, the ordinary scopes are method-based. The table describes that scope check; a request must still pass authentication, tenant isolation, validation and any other checks for its route.

A read key is not a catalog-only key. The general read scope can cover other authenticated read endpoints in its tenant. If your agent should only see selected products, expose an allowlisted catalog tool through your backend and filter the returned fields. Keep the raw key out of the model context.

Likewise, write is broader than “create this one order.” It is not an order-only scope, a spending limit or evidence of buyer approval. Do not invent permission names such as orders:create and assume the API enforces them.

Check the credential before starting the tool loop

The read-only preflight GET /v1/account/auth reports the authenticated tenant, api_key_scopes, has_write_scope and auth_warnings. Call it from your trusted backend and verify the expected tenant. Supply the credential through your deployment's secret configuration.

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.ordercore.ai/v1/account/auth",
    headers={"X-API-Key": os.environ["ORDERCORE_API_KEY"]},
)
with urllib.request.urlopen(request, timeout=15) as response:
    auth = json.load(response)

# Inspect permissions without printing the key or tenant details.
print({
    "scopes": auth["api_key_scopes"],
    "has_write_scope": auth["has_write_scope"],
    "warnings": auth["auth_warnings"],
})

A browsing process can legitimately report missing_write_scope. Treat that as expected for its role. A checkout process that requires ordinary write access should stop before attempting the purchase if its credential is not suitable. For sandbox credentials, inspect the actual scope and allowed routes; a general write flag does not describe every sandbox capability.

Keep the purchase boundary in your backend

1. BrowseThe agent uses a narrow catalog tool backed by a read key.
2. ApproveYour application checks the buyer's intended items, quantity, currency and spending policy.
3. ExecuteA trusted checkout tool uses its write credential for the approved operation.

The agent can propose a purchase, but the executor should validate the operation independently. Recheck current price and availability before execution, and require renewed approval when a material part of the proposal changes. Scope enforcement does not implement those application rules for you.

Once the operation is authorized, give retries a stable identity. See idempotent orders for AI agents for the separate question of avoiding duplicate order writes. Permissions determine whether a write is allowed; idempotency determines how its retries are handled.

Test the denied request as well as the allowed one

Our local middleware tests check that a read scope lets a GET request reach a stub handler and rejects a POST with HTTP 403 and auth_reason: insufficient_api_key_scope. The sandbox tests separately exercise the allowed order and checkout paths and reject routes outside that list.

These tests isolate authorization logic. They do not establish that an entire deployed checkout, payment or credential lifecycle works. In your staging environment, test the real tool executor too: a browse-only process must not be able to acquire a write credential, invoke an unapproved purchase, or leak either credential through its logs.

Use the sandbox for its defined purpose

OrderCore's sandbox_write scope allows selected order and checkout POST operations in the issued sandbox tenant. It does not grant general write access. Payment-intent creation, API-key creation, webhook configuration and inventory changes are outside the sandbox allowlist. The quickstart explains the sandbox flow.

For deployed credentials, plan expiry, rotation and revocation. The authentication reference covers preflight warnings and key lifecycle operations. An empty scope list is not a shortcut to full access: production rejects it by default unless a compatibility override has been enabled.