Skip to content

Authentication

Bearer tokens, the team-owned token model, abilities, and the API access gate

Updated View as Markdown

API access is not included on every plan. Before you build against it, check your store has it: either upgrade to a plan that includes AI & API access, or add the AI & API Access addon from the Addons tab on Billing. Without one, a valid token still gets 403 on every /v1 request — see API access gate below.

Every v1 request carries a personal access token in an Authorization header:

curl https://api.firearmcart.com/v1/orders \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json"

The REST API has no OAuth flow, no API key/secret pair, no request signing, and no session cookie. The bearer token is the entire credential.

AI apps (Claude, ChatGPT, Grok, Muse) connecting to the MCP server sign in with OAuth instead of using a token. Those sign-ins only reach the MCP server, never /v1.


Creating a token

  1. Sign in to https://app.firearmcart.com as the store’s owner or an admin. Team members without the admin role can’t open the API Tokens page.
  2. Switch to the store you want the token to act on. The token is bound to whichever store is current when you create it, and this cannot be changed afterwards.
  3. Open Profile → API Tokens (/user/api-tokens).
  4. Enter a name, tick the abilities you need, and create.

Six read abilities (customers:read, orders:read, fulfillments:read, products:read, shipping:read, taxation:read) are pre-ticked as a read-only default. At least one ability must be selected — a token with no abilities cannot be created.

Token lifetime

Tokens do not expire. There is no configured expiry and no refresh flow. A token is valid until you delete it in the dashboard, which takes effect immediately.

Store tokens like passwords. A leaked token grants everything its abilities allow, for as long as it exists.


Abilities

Each route is guarded by exactly one ability. A token missing that ability gets 403 even if the token is otherwise valid and the store has API access.

Ability Grants Endpoints
customers:read Read customer records and their addresses GET /v1/customers, GET /v1/customers/{customer_id}
customers:write Create or update a customer by email POST /v1/leads
orders:read Read orders, line items, transactions, addresses GET /v1/orders, GET /v1/orders/{order_id}
orders:write Record tracking, send orders to their suppliers, change who ships a line, order notes and the receiving FFL over MCP MCP server only — no v1 REST route
orders:upsell Charge an add-on onto an existing paid order, and calculate its tax first POST /v1/orders/{order_id}/upsell, POST /v1/orders/{order_id}/upsell/tax
fulfillments:read Read fulfillments and their shipments GET /v1/fulfillments, GET /v1/fulfillments/{fulfillment_id}
products:read Read the catalog, variants and media GET /v1/products, GET /v1/products/{product_id}
shipping:read Read shipping zones and their rates GET /v1/shipping
taxation:read Read manual tax zones, and calculate the tax on an order before charging it GET /v1/taxation, POST /v1/taxation/calculate
payments:tokenize Open a hosted card-entry session POST /v1/payments/tokenize
payments:charge Charge a card and create an order POST /v1/payments/charge
subscriptions:read Read Reload subscriptions GET /v1/subscriptions, GET /v1/subscriptions/{uuid}
subscriptions:write Pause, resume, skip, cancel, or edit a subscription POST /v1/subscriptions/{uuid}/pause, /resume, /skip, /cancel, PATCH /v1/subscriptions/{uuid}
ffl:read Search the FFL dealer directory GET /v1/ffl-dealers
settings:read Read store settings, payment gateways (read-only), domains, setup progress, and shipping and tax zones over MCP MCP server only — no v1 REST route
settings:write Change store details, branding and FFL visibility, set the store FFL from a license copy, connect domains, and save shipping and tax zones over MCP MCP server only — no v1 REST route
themes:read Read theme files over MCP MCP server only — no v1 REST route
themes:write Write theme files over MCP MCP server only — no v1 REST route
products:write Edit products (prices, publish status, descriptions, specifications, SEO) and collections over MCP MCP server only — no v1 REST route
inventory:write Change the store’s own stock over MCP MCP server only — no v1 REST route
discounts:read Read discount codes over MCP MCP server only — no v1 REST route
discounts:write Create and update discount codes over MCP MCP server only — no v1 REST route
analytics:read Read sales and traffic summaries over MCP MCP server only — no v1 REST route
blogs:read Read the store’s blogs and blog articles GET /v1/blogs, GET /v1/articles, GET /v1/articles/{article_id}
blogs:write Create blogs, and create or update articles, including from an SEO tool’s publishing webhook POST /v1/blogs, POST /v1/articles, PATCH /v1/articles/{article_id}, POST /v1/articles/webhook

Twenty-five abilities in total. Ten of them do not unlock any /v1 endpoint: themes:read, themes:write, products:write, inventory:write, orders:write, discounts:read, discounts:write, analytics:read, settings:read and settings:write are used only by the MCP server at https://api.firearmcart.com/mcp. The read abilities for customers, orders, products, subscriptions and FFL dealers work on both. blogs:read and blogs:write work on /v1 only: the MCP server’s blog tools use themes:read and themes:write.

The MCP server accepts a token holding any of its abilities and then lists only the tools that token may use: a token holding only themes:read sees the theme read tools, not the theme write tools or the store tools. A token holding nothing but blog abilities is refused there. See Permissions for which ability shows which tools and Tools for the full surface. The MCP server also has its own rate limit; see Rate limits.

Choosing abilities

Grant the narrowest set that works. Two are worth extra thought:

  • payments:charge lets the token move money. Anything holding it can create orders and charge stored cards.
  • orders:upsell does the same on an existing order, and is also the only endpoint that requires you to supply an idempotency key.

A token holding either of those, or payments:tokenize, is refused by the MCP server. Give AI apps their own token without them.


API access gate

Passing the token check is not enough. Every /v1 request also runs an access gate that checks the store’s plan and billing standing, and it can reject you with three distinct responses.

Status Body Meaning
401 {"error": "unauthorized", "message": "Invalid API token."} The credential authenticated, but did not resolve to a store. Practically: the request reached the API as something other than a store token.
403 {"error": "forbidden", "message": "API access is not enabled for this team."} The store’s plan does not include AI & API access, and it holds no AI & API Access add-on.
403 {"error": "subscription_expired", "message": "Your subscription has expired. Please renew to continue using the API."} The store’s subscription is suspended after a failed payment, or is past its cancellation date.

A store passes the gate if any of the following is true: it is a demo account, it has API access granted directly by an administrator, its plan includes API access, or it holds an active API access add-on.

A token that FirearmCart staff created to work on your store, such as on your theme, is marked Staff on the API Tokens page. It passes the gate whatever your plan. Delete it there when the work is done.

Note: Outgoing webhooks don’t go through this gate: they’re included on every plan. See Webhooks.

Note that this gate is distinct from an invalid or deleted token. A revoked, mistyped or missing token fails earlier, at the authentication guard, and produces {"message": "Unauthenticated."} — see Errors.


Always send Accept: application/json

Successful responses are JSON regardless of headers, but error responses are not. Without Accept: application/json:

  • A 401 becomes a 302 redirect to the dashboard login page.
  • A 422 validation failure becomes a 302 redirect rather than a JSON error body.
  • Other failures render an HTML error page.

Send the header on every request, including GETs. The one exception is POST /v1/articles/webhook, which answers in JSON whatever the request asks for, because the SEO tools that call it don’t send the header.


Revoking a token

Delete the token at Profile → API Tokens. Revocation is immediate — the next request with that token fails authentication with 401 Unauthenticated. There is no revocation endpoint; see What the API does not do.

If you suspect a leak, delete the token first and issue a replacement second. There is no way to rotate a secret in place.


  • MCP server — connecting Claude, ChatGPT, Grok and other MCP clients with OAuth or a token
  • Rate limits — per-store request budgets
  • Errors — every failure shape, per status code
  • Team members — who can reach the dashboard page that mints tokens
  • Billing — plans and add-ons that satisfy the API access gate
Navigation

Type to search…

↑↓ navigate↵ selectEsc close