Authentication

Every request carries an API key. Requests for a signed-in user also carry that user’s session. Both are sent by your server.

Keys

Authorization: Bearer sk_test_51Hx…

Key	Prefix	Where it lives	What it can do
Secret	sk_live_…, sk_test_…	Your server’s environment	Everything a storefront does, including acting for a signed-in user.
Publishable	pk_live_…, pk_test_…	Native apps	Public data only: the marketplace, listings, search, categories, catalogue terms, locations.

• Live keys work on https://api.mongrl.com, test keys on https://api.staging.mongrl.com.
• A key belongs to one marketplace, so it also says which marketplace you mean. There’s no marketplace id to send.
• The marketplace’s team creates and revokes keys in the console. A key is shown once.
• A key that doesn’t work (unknown, revoked, malformed) gets 401, never anonymous access.
• GET /v1/marketplace is the quickest way to check a key.

Why your server makes the calls

The API doesn’t accept requests from web pages on other sites, and the secret key must never reach a browser. So your storefront’s server calls mongrl, and your pages call your server. That’s also where sessions stay safe: in an HttpOnly cookie that scripts can’t read.

browser ──your cookie──▶ your server ──sk_… + X-User-Session──▶ mongrl API

Frameworks with server functions or route handlers (TanStack Start, Next.js, Remix, SvelteKit, Nuxt) make this short: one server-only module builds the client per request.

User sessions

Signing in returns a session:

{
  "user": { "id": "4c1e…", "email": "mia@example.com", "first_name": "Mia" },
  "session": { "token": "q8Jx2mR…", "expires_at": "2026-11-18T10:00:00Z" }
}

1. Store session.token in a cookie: HttpOnly; Secure; SameSite=Lax; Path=/. Give it a long life (90 days); the API decides when the session ends.
2. On requests for that user, send it as X-User-Session: <token> together with your secret key.
3. A session ends 30 days after it was last used, and 90 days after sign-in at the latest.
4. Signing out is DELETE /v1/sessions/current. Then clear the cookie.
5. A 401 on a user request means the session has ended: clear the cookie and send them to sign in.

The token is shown only when the session is created. mongrl stores just a hash of it.

Which endpoints need what

Endpoints	Key	Session
/v1/marketplace, /v1/listings, /v1/categories, /v1/catalog-terms, /v1/locations	secret or publishable	no
/v1/users, /v1/sessions…, /v1/password-resets…, /v1/email-verifications	secret	no (they create one)
/v1/me… (profile, listings, orders, favourites, messages, payouts)	secret	yes
/v1/images/{id}/{file}	none	no

Listing responses include favorited (has this user saved it?) only when you send a session.

Common mistakes

• Calling the API from client-side code. Move the call into a server function.
• Putting the token in localStorage. Use an HttpOnly cookie.
• Sharing one client between requests with a session in it. Build the client per request, so one user’s session never leaks into another’s request.