Buyer data and AI clients

​

Scopes

curl --fail-with-body -sS https://api.alura.io/v1/me \
  -H "Authorization: Bearer $ALURA_API_KEY"

interface Me {
  scopes: string[];
}

const res = await fetch('https://api.alura.io/v1/me', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const me = (await res.json()) as Me;

// Each Your shop scope, and what this key can read with it.
const yourShop: [string, string][] = [
  ['workspace:read', 'shops, settings, stats, listings, reviews, changes and syncs'],
  ['orders:read', 'orders, with buyer names, addresses and messages'],
  ['customers:read', 'customers'],
];
for (const [scope, reads] of yourShop) console.log(`${me.scopes.includes(scope) ? 'yes' : 'no '} ${scope}: ${reads}`);

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/me",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    me = json.load(response)

# Each Your shop scope, and what this key can read with it.
your_shop = [
    ("workspace:read", "shops, settings, stats, listings, reviews, changes and syncs"),
    ("orders:read", "orders, with buyer names, addresses and messages"),
    ("customers:read", "customers"),
]
for scope, reads in your_shop:
    print(f"{'yes' if scope in me['scopes'] else 'no '} {scope}: {reads}")

​

Workspace permissions

​

What counts as buyer data

• Buyer names, on orders, on customers and on the buyer of a review.
• Shipping addresses on orders.
• Messages: message_from_buyer, message_from_seller and gift_message on orders.
• Order IDs on reviews, because they link a review to the buyer’s order.
• Customer details: location, number of orders, items, spending, refunds and reviews.
• Review text and photos, written and taken by buyers (a review’s image_url).
• Buyer profile images on customers (image_url).

​

How the API limits it

• Addresses and messages only when asked, over MCP. get_my_order returns them only with expand: ["shipping_address"] or expand: ["messages"]. Search results never carry them, only the buyer’s name. Over REST, GET /v1/workspace/orders/{id} returns both by default.
• A missing address says why. shipping_address is null, never an empty string, with shipping_address_error: etsy_restricted when Etsy didn’t give Alura the address, no_physical_items for an order of digital items only, or not_fetched when Alura hasn’t stored the order’s items.
• Buyer names never go in a URL. URLs end up in browser history and server logs. GET /v1/workspace/orders takes only an exact order ID in q. To search by buyer name, send q in the body of POST /v1/workspace/orders/search. Customers work the same way with POST /v1/workspace/customers/search, which also takes country. The MCP search tools use these routes. Alura’s request log doesn’t record the search text.
• Cursors reveal nothing. The cursors of order and customer lists are encrypted, so a cursor in a log shows neither the search nor where it stopped. Treat every cursor as an opaque string.

​

Your AI client receives what it reads

​

Text from buyers is data, not instructions

​

Next steps