Skip to main content

Authentication & access

Applies toEDITED MCPQuery APIJobs API

Every request to EDITED — whether you call the MCP server or either REST API — carries the same access key in the x-api-key header. One credential, issued once, works across every surface — there are no separate per-product keys to juggle. With key-based authentication there's nothing else to manage: no token refresh, no session — just one header, sent on every call.

Connecting a chat assistant instead?

This page is about building against EDITED with an access key. If you're connecting an AI assistant — Claude, ChatGPT or Microsoft Copilot — to chat with EDITED data, you don't use a key; you sign in once instead. See Using EDITED in chat.

One key, every surface​

The access key you get from EDITED is not per-product. The same key authenticates MCP, the Query API, and the Jobs API — so a builder who already calls MCP holds the credential the REST API needs, and vice versa. What differs between surfaces is only the base URL you send it to, never the key or the header.

SurfaceBase URL
EDITED MCPhttps://mcp.edited.com/mcp/v1
Query APIhttps://apis.edited.com/query/v1/apparel/
Jobs APIhttps://api-us.edited.com/v1 · https://api-eu.edited.com/v1

The Query API host also serves the Schema API discovery endpoints at https://apis.edited.com/schema/v1/ — same key — for resolving brand, retailer, and category values. See the Schema API reference.

One key, but access is still per-subscription

Authentication is unified: the same key proves who you are on every surface. Access is not. What your key can actually reach depends on your subscription — being provisioned for one surface or data domain doesn't automatically provision you for another. An unprovisioned call still authenticates, then is refused at the next layer (see Errors).

Not sure which surface you want? See MCP or the API?.

Get your key​

Your access key is issued by EDITED when your contract starts. To request one — or to check whether your existing EDITED account already includes access — contact your EDITED account manager or customer success representative, or email support@edited.com.

Send the key​

Add the x-api-key header to every request. The header is identical on every surface; only the URL and the rest of the request differ.

curl -s https://mcp.edited.com/mcp/v1 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

The MCP-Protocol-Version and Accept headers are MCP's, not authentication's — see the Quickstart. With the official SDKs, set x-api-key once on the transport and every call inherits it — see Connect a custom client.

When authentication fails​

How a rejected key looks depends on the surface:

  • MCP answers 401 Unauthorized whether the key is missing or just not accepted (unknown, or not enabled for MCP).
  • The Jobs API answers 401 when the key is missing, and 403 Forbidden when it's present but not accepted (unknown, or without access to the surface).
  • The Query API answers 403 Forbidden either way — its gateway rejects the request before the key is checked, so a missing key and an unknown one are indistinguishable. A 403 here doesn't tell you why the key failed, so check first that the x-api-key header is actually being sent.

Either way it's the key at fault, not your request body. Sending any request and reading the status is still the quickest way to sanity-check a new key — just read it per surface, since a 401 isn't guaranteed everywhere.

Don't read that as "this data isn't included in my plan," though. A key that authenticates but lacks access to a specific surface or backend is refused a layer deeper — a JSON-RPC -32003 on MCP, or an HTTP 403 on the REST APIs. See Errors for the full model on each surface.

Keep your key safe​

Treat the key like a password:

  • Use environment variables, not source code or committed config. The Claude Code recipe shows the ${EDITED_MCP_API_KEY} pattern that keeps a shared .mcp.json free of secrets; the same discipline applies to a REST client's config.
  • The "Try it" widget stores your key in your browser only (localStorage) — it is never sent anywhere except the MCP endpoint.
  • Rotate a leaked key immediately by contacting your EDITED account manager or support@edited.com. Because one key spans every surface, a leaked key exposes all of them — rotate it as soon as you suspect exposure.

Wondering who can see your key, or what the connection can and can't reach? See Data privacy & security for the security shape of the connection.