Authentication and API keys

Every request to the Merch API authenticates with a bearer token in the Authorization header. Get a key from the customer portal, send it on every call, and rotate it when needed.

#Where to get a key

Open the customer portal, go to Settings → API Keys, and create a key. The full key is shown to you once on creation — copy it into a secrets manager immediately. The portal stores only a hashed reference, so a lost key cannot be recovered. Create a new one if you lose access.

For the AM-supported, customer-facing walkthrough (creating, naming, and revoking keys in the portal), see API keys and integrations.

#Sending the key

Send the key as a bearer token on every request:

Authorization: Bearer <your_api_key>

Keys are exactly 96 characters. The auth middleware checks the length before it does anything else — if the value you send is shorter or longer, the request is rejected with 401 Unauthorized and a plain-text body of Unauthorized (not JSON, not a structured error).

#Reasons you'll see a 401

• The Authorization header is missing entirely.
• The scheme is not Bearer (for example, Basic or Token).
• The header is present but the key portion is empty.
• The key is not 96 characters.
• The key is well-formed but not recognized — either it was never issued, was revoked, or belongs to a deactivated account.

In every case the response body is the literal text Unauthorized.

#Rotation

Rotate keys periodically — and immediately if you suspect one has leaked. Create the new key first, deploy it to the systems that need it, then revoke the old key in the portal. Revocation takes effect on the next request: any in-flight call already accepted by the gateway will complete, but the next call with the old key returns 401.

If you have several keys for the same integration (for example, one per environment), name them descriptively so you can revoke the right one without breaking unrelated traffic.

#Sanity-check your key

The /v1/auth endpoint exists for exactly one purpose: confirming your key is being parsed and accepted. It accepts any HTTP method and returns your account id on success.

curl -X GET 'https://api.merch.com/v1/auth' \
  -H 'Authorization: Bearer <your_api_key>'

{
  "account_id": "<your_account_id>",
  "message": "Authentication successful"
}

If you get Unauthorized back instead, walk through the 401 reasons above before debugging further. Most issues are header formatting.