API reference

Two calls and an MCP server, all with an API key. Send JSON, get a signed JSON answer. Every example uses test.authorizedretailers.ai, a demo brand the registry runs, so you can try it as written.

Overview

API keys

The verify and resolve calls and the MCP server need an API key, so we know who is using the registry and can reach you about it. Get an API key, and your console in the app opens with your keys, their usage and your settings. Come back with Sign in, then Agent developer. We ask for:

• your work email. If you don't have one, say so on the form and tick the box to be contacted, and we'll get in touch;
• your name and organization, as the agent's operator;
• the agent you're building and what it's for.

• You sign in with an emailed link and an authenticator app, as brand accounts do. Lost your phone? Email hello@authorizedretailers.ai and we'll reset it.
• Send the key as Authorization: Bearer <key> on every call, and never in a URL or the request body.
• A key is shown once, when you create it. Keep it in your agent's secrets, not in code or a repository.
• Make as many keys as you need and revoke any of them. A revoked key stops working within a minute.
• No key, or one that isn't valid, gets a 401 (api_key_required or invalid_api_key) and no answer. Treat the seller as unconfirmed, and check the key: the registry is up.
• A key never changes an answer. Everyone who asks the same question gets the same signed answer.
• The signing keys, public lists and the revocation feed (below) need no key.
• The rules for keys are in spec section 9.6.

Verify a seller

On a product page you see a product and a seller. Send both. The answer says whether the brand has authorized that seller on that channel, in that territory, for that product, and flags anything you should know about the product.

Parameters

A JSON body. Send a product, a brand_domain or both; the registry finds the brand from the product in the catalogs of verified brands, so a lookalike brand can't claim another brand's products.

Answers

Every answer carries status. Answers about a brand also carry brand (its domain and name) and resolved_by (brand_domain, gtin, asin, walmart_item_id or wpid), so you know how the registry found it.

New statuses can be added. Treat any status you don't recognize as unconfirmed, never as authorized.

The product

Trusting an answer

Every answer is signed by the registry: a detached JWS (RFC 7515) with Ed25519 (EdDSA) over the answer's JSON, canonicalized per RFC 8785 without its signature. Check it against the registry's keys at /.well-known/jwks.json, using the kid the signature names. Cache the key set for no longer than the 5 minutes it is served for, since a compromised key is removed from it at once. If you don't recognize the kid, fetch the keys again once. Details are in spec section 8.

• An answer stays fresh for 15 minutes (valid_until), so an answer you saved earlier can be used for 15 minutes at most. This is about the answer, not the authorization, which lasts until the brand revokes it or it reaches its own end date (expires). A brand's revocation reaches new answers within a minute.
• If the verify API can't be reached, you may use an answer you already hold until its stale_until (24 hours), but only after checking it against a revocation feed issued at or after the answer, and you must mark it as stale. A feed issued before the answer says nothing about later revocations.
• An answer that carries expires, the authorization's own end date, stops being usable as authorized at that instant, even if its valid_until is later.
• observed: null only means the registry has no sighting of the seller. Don't treat it as a warning, and don't downgrade an authorized answer because of it.
• If you can't get a current answer, treat the seller as unconfirmed. An outage never makes a seller authorized or unauthorized.

Examples

The first demo case, an Amazon seller the demo brand has authorized, as cURL, Node.js and Python. The response is what the registry returned (signature shortened).

curl -s https://authorizedretailers.ai/verify \
  -H "Authorization: Bearer $AR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": {
      "domain": "amazon.com",
      "seller_id": "ADEMOSELLER001"
    },
    "product": {
      "asin": "B0DEMO0001"
    }
  }'

const res = await fetch("https://authorizedretailers.ai/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + process.env.AR_API_KEY },
  body: JSON.stringify({
    "channel": {
      "domain": "amazon.com",
      "seller_id": "ADEMOSELLER001"
    },
    "product": {
      "asin": "B0DEMO0001"
    }
  }),
});
const answer = await res.json();
if (answer.status === "authorized") { /* go ahead, after checking answer.product?.status */ }

import os
import requests

r = requests.post("https://authorizedretailers.ai/verify", headers={"Authorization": f"Bearer {os.environ['AR_API_KEY']}"}, json={
  "channel": {
    "domain": "amazon.com",
    "seller_id": "ADEMOSELLER001"
  },
  "product": {
    "asin": "B0DEMO0001"
  }
})
answer = r.json()
if answer["status"] == "authorized":
    pass  # go ahead, after checking answer.get("product", {}).get("status")

Every case the demo brand covers, with the exact body to send. Pick one in the live check below, or press Run.

curl -s https://authorizedretailers.ai/verify \
  -H "Authorization: Bearer $AR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": {
      "domain": "amazon.com",
      "seller_id": "ADEMOSELLER001"
    },
    "product": {
      "asin": "B0DEMO0001"
    }
  }'

{
  "status": "authorized",
  "brand": { "domain": "test.authorizedretailers.ai", "name": "Authorized Retailers Demo" },
  "resolved_by": "asin",
  "authorization_id": "auth_demo000000000000000000001",
  "revocation_id": "rv_5069f69c213b49aee224b948",
  "checked": "2026-10-07T19:35:35.707Z",
  "valid_until": "2026-10-07T19:50:35.707Z",
  "stale_until": "2026-10-08T19:35:35.707Z",
  "product": {
    "in_catalog": true, "id": "DEMO-TEE", "product_line": "Demo Tees", "name": "Demo Tee",
    "mpns": ["DT-100"], "style_code": "DEMO-TEE"
  },
  "observed": null,
  "signals": [],
  "signature": { "kid": "ar-20260924-6e37", "jws": "eyJhbGciOiJFZERTQSIs..." }
}

The demo brand's signed list: /brands/test.authorizedretailers.ai/list.

Resolve a product

Which brand does a product belong to, without asking about a seller.

curl -s https://authorizedretailers.ai/resolve \
  -H "Authorization: Bearer $AR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "product": { "gtin": "200000001018" } }'

The signed answer is resolved (with brand), product_not_found or brand_ambiguous (with candidates). It names the brand and nothing else.

Errors and limits

Say who you are. Send a User-Agent that names your agent and its operator and a way to reach you, for example ExampleShopper/2.1 (+https://example.com/agent; agents@example.com). We record it with the name of the network owner to see which agents use the registry and, where you name yourself, to get in touch. It never changes an answer, and sending none is fine. See the privacy policy.

Where to check in a checkout flow

Protocols for agents that buy, such as UCP and ACP, say how to find a merchant's products and check out with it. They don't say whether a brand authorized that merchant, and a merchant can't vouch for itself. Check between choosing a seller and starting checkout, using the seller's channel: its store domain, or its marketplace and seller ID. Start checkout only with a seller the brand has authorized, or one the shopper has chosen knowing it's unconfirmed. Never start it with a seller the brand has declared unauthorized unless the shopper has confirmed that purchase knowing what the declaration means (see unauthorized above).

MCP server

Prefer tools? Connect the remote MCP server at https://authorizedretailers.ai/mcp (Streamable HTTP; send your key as Authorization: Bearer <key>). Four read-only tools:

Connect a client

Every client sends the same thing: your key in an Authorization: Bearer <key> header, on every request. Put the key in an environment variable or the client's secret store, not in a file you commit.

Some hosted chat apps connect to a server only by signing in with OAuth and have no place to put a key. They can't use the MCP server yet. Your agent can still call the REST API, which does the same thing.

A call without a valid key gets HTTP 401 with WWW-Authenticate: Bearer realm="authorizedretailers.ai". Listing the tools needs no key, so a client can connect and show them before you add one.

Schemas and spec

• JSON Schemas for every request and answer: verify request, verify response, resolve request and resolve response.
• The rules behind all of this: spec section 9 and finding the brand from a product and buying from a seller the brand hasn't authorized. The spec is published as @authorizedretailers/spec 0.8.0, with schemas, fixtures and reference code.
• Signing keys: /.well-known/jwks.json. Revocations: /revocations.