Metr Fit / API V1

Authentication and store isolation

Keep Metr credentials on your server and use the smallest scope each integration needs.

Three levels of access

Credential	Purpose
Operator bootstrap key	POST /v1/merchants only. Stored outside merchant integrations.
Merchant admin key	Create stores, manage keys and access the merchant’s resources.
Store-scoped key	Only its named store and granted scopes. Never another store.

Authorization: Bearer YOUR_SECRET_API_KEY

API keys are returned once and stored as SHA-256 digests. There is no login endpoint or token refresh flow. Create a replacement key before revoking an old key.

Issue a scoped key

curl --fail-with-body -X POST "$METR_API_URL/v1/api-keys" \
  -H "Authorization: Bearer $METR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "Store integration",
  "store_id": "REPLACE_WITH_STORE_ID",
  "scopes": [
    "catalog",
    "fit",
    "events",
    "analytics"
  ]
}'

Scope	Access
admin	Merchant administration, or resource administration limited to a named store. Store-bound admin cannot issue keys or create stores.
catalog	Products, variants, size charts and product types.
fit	Questionnaires, sessions, recommendations and decisions.
events	Send and read customer/order events.
analytics	Read descriptive cohort metrics.

Non-admin keys must specify store_id. Optional expires_at must be a future RFC3339 timestamp within one year. Key issuance and listing require an unrestricted merchant admin key.

Revocation

curl --fail-with-body -X DELETE "$METR_API_URL/v1/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $METR_API_KEY"

Revoked keys immediately receive 401. A key cannot revoke itself. Create or use another admin key for rotation.

Browser and integration safety

Do not put secret keys in themes, browser JavaScript, mobile apps, URLs or analytics. Your backend must authorize the customer’s session before forwarding answers. Validate webhook signatures in your integration before forwarding purchase/return events. The optional seller console supports accounts, store-scoped keys and Shopify OAuth authorization. Shopify catalog sync, storefront proxy and outcome webhooks are not implemented yet.