Login API reference

The endpoints behind the custom login forms and the password recovery form.

API reference

If you want to handle form submissions with JavaScript instead of using target="_blank", you can submit requests via fetch and display success or error messages inline. All endpoints below accept application/json. Error bodies differ by service: /auth/* endpoints return a plain-text message (read with res.text()), while /api3/* endpoints return JSON { message } (read with res.json()) — see General error format.

POST /auth/public/login

Authenticates a vendor and sets session cookies.

Request body:

Field	Type	Required	Description
email	string	yes	Vendor email address
password	string	yes	Password (minimum 8 characters)
redirect	string	no	Path to redirect to after login (e.g. /)

Success (201): Empty body. A session cookie (garnet-session-token) is set automatically. Redirect the user to their dashboard:

const res = await fetch('https://your-store.garnet.center/auth/public/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ email, password }),
});
if (res.ok) {
  window.location.href = '/'; // redirect to dashboard
} else {
  showError(await res.text()); // /auth/* error bodies are plain text, not JSON
}

Error responses:

Status	Message	When
400	email is a required field	Missing or invalid email
400	password must be at least 8 characters	Password too short
401	Invalid email or password	Wrong credentials
401	User is not verified	Account not yet verified
401	You don't have access to this marketplace	User exists but not on this store
429	Rate limit exceeded	More than 60 requests per minute

POST /auth/public/change-password/request

Sends a 6-character reset code to the user's email. The code is valid for 15 minutes.

Request body:

Field	Type	Required	Description
email	string	yes	Vendor email address

Success (201): Empty body. For security, the endpoint returns 201 even if the email does not exist. Always show a generic message like "If an account exists with this email, a reset code has been sent."

Error responses:

Status	Message	When
400	email must be a valid email	Invalid email format
429	Code already sent, please wait before sending another code.	Less than 1 minute since last code

POST /auth/public/change-password/update

Sets a new password using the reset code. On success, the user is automatically logged in (session cookie is set).

Request body:

Field	Type	Required	Description
email	string	yes	Vendor email address
code	string	yes	6-character reset code from email
password	string	yes	New password (minimum 8 characters)
redirect	string	no	Path to redirect to after login (e.g. /)

Success (201): Empty body. Session cookie is set — redirect the user to their dashboard.

Error responses:

Status	Message	When
400	password must be at least 8 characters	Password too short
400	Incorrect code or link has expired	Wrong code or user not found
400	Expired code	Code is older than 15 minutes
401	You don't have access to this marketplace	User exists but not on this store

POST /api3/public/vendor

Registers a new vendor on the marketplace. Requires vendor registration to be enabled.

Request body:

Field	Type	Required	Description
email	string	yes	Vendor email address
password	string	no	Password (minimum 10 characters)
vendor	string	yes	Vendor name
csrfToken	string	yes	CSRF token from /api3/public/csrf-token
profile	object	no	Custom profile fields (key-value pairs)

Success (201): Empty body. The vendor is either approved immediately or placed in a pending approval queue, depending on your marketplace settings.

Error responses:

Status	Message	When
400	Invalid submission	Bot protection triggered
400	Invalid or expired token	CSRF token is invalid or expired
400	Please wait before submitting	Form submitted too quickly after loading
400	Public registration is not enabled	Vendor registration is disabled
400	Vendor already exists	Vendor name is already taken
400	Email already exists	Email is already registered

General error format

All error responses return JSON with a message field:

{ "message": "Error message describing what went wrong" }

You can use this to display inline error messages:

const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
if (!res.ok) {
  const { message } = await res.text();
  document.getElementById('error').textContent = message;
}