Authentication And Scopes

Catalog APIs, procurement APIs, webhook ingestion, UCP endpoints, and MCP requests use developer API keys.

Where To Create An API Key

API keys are created in the Merchant Dashboard:

Merchant Dashboard > Developers > API Keys > Create New Key

For full dashboard setup, store creation, sub-merchant setup, and key type guidance, see Dashboard Setup.

Create An API Key

1. Sign in to the Merchant Dashboard.
2. Select the merchant account.
3. Open Developers.
4. Open API Keys.
5. Click Create New Key.
6. Choose a clear name, for example ERP Catalog Production or Procurement Sync Production.
7. Choose the access scope.
8. Select stores if the chosen scope requires it.
9. Choose how long the key remains valid: a number of minutes, hours, days, months, or years, or Never for no automatic expiration.
10. Create the key and copy it immediately.

API keys are shown only once.

Expiration, Revocation, And Deletion

• A key with an expiration becomes invalid at expiresAt; expiration does not delete the row or its audit history.
• Never stores no expiration timestamp. Use it only when the integration has an external rotation policy.
• Revocation is immediate and permanent. A revoked key cannot authenticate even if its expiration date is still in the future.
• A key must be revoked before it can be permanently deleted. This rule is enforced by the server for both single-key and bulk actions.
• Expired keys are not automatically revoked. Revoke an expired key first if it must be deleted.
• The Developers table displays expiration and revocation timestamps in English using a deterministic timezone so server and browser rendering match.
• Bulk revoke acts on the non-revoked keys in the current selection and is disabled when none are revocable. Bulk delete is available only when every selected key has already been revoked.

Example key:

tr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authentication Headers

Recommended:

Authorization: Bearer tr_live_your_key_here

Alternative:

x-api-key: tr_live_your_key_here

For MCP clients that support custom headers, use:

Authorization: Bearer tr_live_your_key_here

or:

X-Catalog-API-Key: tr_live_your_key_here

For procurement-specific clients, the equivalent explicit header is:

X-Procurement-API-Key: tr_live_your_key_here

Inbound webhook ingestion through the webhook service accepts the same developer key:

Authorization: Bearer tr_live_your_key_here

or:

X-Catalog-API-Key: tr_live_your_key_here
X-Procurement-API-Key: tr_live_your_key_here

Use only the header for the namespace you are calling.

Access Scopes And Key Types

Dashboard Label	API Scope	Access
Merchant stores only	merchant	Stores owned directly by the selected merchant. Excludes sub-merchants.
Single store	store	One selected store only.
Merchant + sub-merchants	merchant_network	Main merchant stores and sub-merchant stores.
Custom stores	custom	Only the selected stores.

Scope is enforced server-side. Passing another storeId in the request does not override the key's scope.

Recommended choices:

Scenario	Recommended Key
One ecommerce store integration	Single store
Main merchant ERP/PIM sync	Merchant stores only
Marketplace or franchise network sync	Merchant + sub-merchants
Pilot rollout to selected stores	Custom stores
MCP/agent access to one store	Single store
Procurement supplier/inventory sync for one store	Single store
Central procurement integration across many stores	Merchant + sub-merchants or Custom stores

Verify Key Access

Use the stores endpoint first:

curl "https://merchant.thyris.cloud/api/v1/catalog/stores" \
  -H "Authorization: Bearer tr_live_your_key_here"

For procurement:

curl "https://merchant.thyris.cloud/api/v1/procurement/stores" \
  -H "Authorization: Bearer tr_live_your_key_here"

Optional search:

curl "https://merchant.thyris.cloud/api/v1/catalog/stores?q=Example City" \
  -H "Authorization: Bearer tr_live_your_key_here"

Response:

{
  "success": true,
  "data": [
    {
      "id": "store_uuid",
      "name": "Main Store",
      "slug": "main-store",
      "merchantId": "merchant_uuid",
      "currency": "USD",
      "language": "en"
    }
  ]
}

Key Handling

• Store keys in a backend secret manager or encrypted environment variable.
• Do not expose keys in frontend code, mobile apps, browser extensions, or public repositories.
• Rotate a key immediately if it is exposed.
• Prefer a finite expiration for production integrations and rotate before it is reached.
• Revoke a key before removing it; deletion is intentionally unavailable for active or merely expired keys.
• Use separate keys for staging and production.
• Prefer a store-scoped key when an integration only touches one store.
• Use separate keys for catalog sync and procurement sync when different vendor systems own those workflows.

Authentication Errors

401 Unauthorized means:

• The key is missing.
• The key is invalid.
• The key was revoked.
• The key expired.
• The merchant account is not active.

403 Forbidden means:

• The key is valid but does not have access to the requested store, product, cart, or order.
• The key has no configured store access.