Authentication

Production Partner API access uses the marketplace sign-in session. Your integration exchanges that session for a short-lived seller-scoped Partner API token.

API access is arranged through seller onboarding. Do not build a production integration against development-only password-token endpoints.

Not offered yet as self-service: long-lived machine API keys managed only in Account (for unattended ERP jobs without a seller browser session). Until that product ships, automated clients should use the exchange flow with a seller session, and day-to-day bulk catalogue work should use Partner Portal spreadsheet import under Inventory.

Before you start

You need:

• a verified Partner Portal seller account
• multi-factor authentication enabled
• API access enabled or arranged for your account
• a current marketplace access token for the signed-in seller

Exchange a marketplace token

POST /api/v1/auth/exchange

Send the current marketplace access token to obtain a Partner API token.

POST /api/v1/auth/exchange
Content-Type: application/json

{
  "supabase_token": "<marketplace-access-token>"
}

The exchange verifies the marketplace session, requires Authenticator Assurance Level aal2, resolves the seller account, and issues a seller-scoped token.

Success response:

{
  "access_token": "<partner-api-token>",
  "token_type": "bearer",
  "seller_id": "slr_01HY5X3K7QNXV8BDEF3G4H5J6M"
}

Status	Meaning
401	Marketplace token is invalid, expired, or missing required identity claims
403	MFA assurance is below aal2
404	No seller account matches the marketplace identity
503	Marketplace authentication is temporarily unavailable

Create or bind the seller profile

POST /api/v1/auth/register

Use this only after authenticating with the marketplace service. It creates or binds the seller profile; it does not issue the Partner API token. Call /api/v1/auth/exchange afterwards.

POST /api/v1/auth/register
Authorization: Bearer <marketplace-access-token>
Content-Type: application/json

{
  "business_name": "Example Seller",
  "tax_id": "12345678901"
}

Use the Partner API token

Send the exchanged token on every authenticated Partner API request:

Authorization: Bearer <partner-api-token>

The token identifies the seller and carries the roles and permissions used by the API. Treat it as a short-lived credential: keep it out of logs, browser URLs, source control, and support screenshots.

MFA requirement

Production token exchange requires aal2. If exchange returns 403, complete MFA in the marketplace account and retry with the refreshed marketplace session.

Seller data isolation

Partner API responses are scoped to the seller identified by the exchanged token. Do not send a seller identifier from user input to try to switch account context; sign in as the intended seller and exchange that seller’s marketplace session.

Common issues

Symptom	Action
401 invalid or expired token	Refresh the marketplace session, then exchange again
403 MFA required	Complete MFA and retry exchange
404 seller account not found	Finish seller registration or contact onboarding support
503 authentication unavailable	Retry with backoff; check the public status page if the problem continues

Next: Integration Guide · Error Reference