Authentication

Marka has two programmatic credentials, and which one you want depends on whether there is a browser in the loop.

Prefer the OAuth token where it applies. Nothing is pasted anywhere, the token is short-lived, and disconnecting one client does not disturb any other. The whole flow is described on MCP overview — your client discovers it from the 401 the gateway answers with.

Everything below is about the API key, which is the credential /api/v1 speaks. Create a key under Settings → API keys; Getting started walks through it and your first call.

Sending the key

Two header forms work, and they are equivalent:

x-api-key: mk_YOUR_KEY_HERE

Authorization: Bearer mk_YOUR_KEY_HERE

x-api-key is the primary form — it is what the OpenAPI security scheme declares, what the SDK sends, and what the hosted MCP config snippet emits. The Authorization: Bearer spelling is accepted because it is what most HTTP clients and MCP configurations reach for. Both forms work at both doors: /api/v1/* and /api/mcp.

Two details worth knowing:

• If both headers are present, x-api-key wins. They are never merged.
• Only mk_-prefixed bearer tokens are treated as API keys. An Authorization header carrying anything else is left alone rather than fed to the key validator, so an unrelated token does not turn into a spurious "invalid key".

Browser sessions

/api/v1/* additionally accepts a signed-in browser cookie, so you can explore your own API from a logged-in tab without minting a key first. This is an interactive convenience and is deliberately not part of the contract a client programs against — treat the API key as the credential.

/api/mcp takes an OAuth access token or an API key, and not a cookie session. Its tools mutate listings, and it stays a credential-bearing machine endpoint rather than a second, cookie-authenticated door into those mutations. A request with no usable credential answers 401 with a WWW-Authenticate header naming the discovery document — that header is how a client that knows nothing but the URL finds its way to the browser sign-in.

The same rule covers OAuth: an API key cannot start an authorization, and Settings → Connected apps is a signed-in-browser surface. A leaked key can neither mint a successor key nor trade itself for an OAuth grant that would survive revoking it.

Key lifecycle

A key that is missing, malformed, never issued, revoked, or expired all answer the same way: 401.

OAuth token lifecycle

Disconnecting removes the grant and every token issued under it, so it takes effect on the next request rather than when the current access token happens to expire. A client whose token has been disconnected gets the same 401 and discovery challenge it got before it was ever connected, so it can simply ask again.

Rate limits

Each key carries its own request budget: 1000 requests, over a 60-second window.

That window is worth reading carefully, because it does not measure elapsed time — it measures idle time. The counter resets only after 60 consecutive seconds during which the key made no request at all; every allowed request pushes the reset out again. In practice the budget behaves like 1000 requests per burst of activity, and a client that keeps polling without ever going quiet will eventually spend it.

Exceeding it answers 429:

{ "error": "Rate limit exceeded for this API key.", "code": "rate_limited" }

The remedy is to stop for a minute, or to spread work across more than one key. There is no published retry-after header on this surface.

Errors

Every non-2xx response on /api/v1 uses one envelope:

{
  "error": "Human-readable message.",
  "code": "optional_refinement"
}

error is always present and is written for you — it never carries provider or database internals. code is optional and is not an enum: it carries either an API-level code or the originating domain error code (listing.authority_locked, subscription.tier_too_low, …), and new codes appear without a contract change. Branch on the status first; treat code as a refinement.

Statuses

Anything outside that set (a 502 or 503 from a failed upstream) is an operational condition, not part of the contract.

Codes you will actually branch on

Where keys are not enough

Reading is available to any valid key. Key-authenticated writes — createListing, updateListing, publishListing — additionally require the api_write entitlement, which is a Pro-or-higher feature. See Plans & limits.