Authentication

Authenticate with a bearer API key, then verify the org, contract version, scopes, acting user, and effective capabilities before running a workflow.

The API key is a secret in the form sk_.... It is shown once when issued. Store it outside source control and read it from the environment.

Base URL

Production:

https://app.shelfcycle.com/api/v1

Local development:

http://localhost:3000/api/v1

The route major remains /api/v1. The v1.35 contract is reported by GET /me and the OpenAPI document as apiContractVersion or info.version. GET /me also reports minimumCompatibleContractVersion so integrations can verify their supported compatibility floor.

Check contract compatibility

Treat contract versions as numeric major.minor.patch values, not text and not an exact-equality check. Remove one leading v, accept two or three numeric segments, and treat a missing patch as zero. A client version is supported when it is at least minimumCompatibleContractVersion and no newer than apiContractVersion.

For example, v1.34.1 becomes [1, 34, 1] and is compatible with a server reporting v1.35. After the version check, confirm the workflow's required scopes, effective capabilities, and OpenAPI operation ids. If a version is malformed, inspect the current contract before continuing.

Required header

Every API request uses the bearer token header.

Authorization: Bearer <SHELFCYCLE_API_KEY>

Recommended client metadata:

X-ShelfCycle-Client: Email notes automation
X-ShelfCycle-Request-Source: local-agent

Verify with /me

GET /me is the first request a workflow should make. It confirms the key, tenant, contract, scopes, acting user, documentation links, and effective capabilities after live RBAC.

curl "$SHELFCYCLE_API_BASE_URL/me" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Email notes automation"

{
  "data": {
    "apiVersion": "v1",
    "apiContractVersion": "v1.35",
    "minimumCompatibleContractVersion": "v1.21",
    "org": { "id": "org-id", "name": "Northstar Chemical", "baseCurrencyCode": "USD" },
    "key": {
      "id": "api-key-id",
      "name": "Email notes automation",
      "purpose": "Workflow for creating notes from source emails",
      "preview": "sk_...abcd",
      "scopes": ["company-reference:read", "search:read", "tags:read", "notes:read", "notes:write", "customers:read", "products:read"],
      "accessMode": "restricted",
      "storedGrants": ["company-reference:read", "search:read", "tags:read", "notes:read", "notes:write", "customers:read", "products:read"],
      "effectiveScopes": ["company-reference:read", "search:read", "tags:read", "notes:read", "notes:write", "customers:read", "products:read"],
      "retiredScopes": [],
      "expiresAt": null
    },
    "actor": { "type": "user", "id": "user-id", "displayName": "Jordan Buyer" },
    "documentation": {
      "openapiJsonUrl": "https://app.shelfcycle.com/api/v1/openapi.json",
      "llmsTxtUrl": "https://app.shelfcycle.com/llms.txt"
    },
    "effectiveCapabilities": {
      "documentUploads": { "create": false },
      "search": { "viewableTypes": ["customer", "contact", "product", "order", "purchase_order", "location"] },
      "entityResolution": { "viewableClasses": ["customer", "product", "product_family"] },
      "tags": { "vocabulary": true, "viewableEntityTypes": ["customer", "product", "product_family"] },
      "productDirectory": { "view": true },
      "notes": {
        "create": true,
        "view": true,
        "update": true,
        "activityReport": true,
        "viewableSubjectTypes": ["customer", "product"]
      },
      "opportunities": { "view": false, "create": false, "update": false, "close": false, "metaUpsert": false },
      "contacts": {
        "create": false,
        "view": false,
        "update": false,
        "customer": { "create": false, "view": false, "update": false },
        "supplier": { "create": false, "view": false, "update": false }
      },
      "customers": {
        "create": false,
        "view": true,
        "update": false,
        "locations": { "view": true, "create": false, "update": false },
        "addresses": { "view": true, "create": false, "update": false },
        "documents": { "view": true, "create": false }
      },
      "suppliers": {
        "create": false,
        "view": false,
        "update": false,
        "shipFromLocations": { "view": false, "create": false, "update": false },
        "documents": { "view": false, "create": false }
      },
      "companyReference": { "activeDirectory": true, "customers": true, "suppliers": false },
      "products": {
        "view": true,
        "create": false,
        "update": false,
        "documents": { "view": true, "create": false },
        "sds": { "view": true, "update": false }
      },
      "productFamilies": { "view": true, "create": false, "update": false },
      "costBookEntries": { "view": false, "create": false },
      "currentCostSources": { "read": false, "write": false },
      "priceBookEntries": { "read": false, "write": false, "writeCurrencyMode": "org_base_only" },
      "orders": { "view": false, "changedRecordDiscovery": false },
      "purchaseOrders": {
        "view": false,
        "changedRecordDiscovery": false,
        "execution": { "view": false, "currentStateRefresh": false },
        "documents": { "view": false, "create": false }
      },
      "inventory": { "balances": { "view": false, "currentStateRefresh": false } },
      "reports": { "available": [] },
      "writeReadiness": {
        "notes": { "create": true, "update": true },
        "opportunities": { "create": false, "update": false, "close": false, "metaUpsert": false },
        "contacts": {
          "create": false,
          "update": false,
          "customer": { "create": false, "update": false },
          "supplier": { "create": false, "update": false }
        },
        "customers": {
          "create": false,
          "update": false,
          "locations": { "create": false, "update": false },
          "addresses": { "create": false, "update": false },
          "documents": { "create": false }
        },
        "suppliers": {
          "create": false,
          "update": false,
          "shipFromLocations": { "create": false, "update": false },
          "documents": { "create": false }
        },
        "products": {
          "create": false,
          "update": false,
          "documents": { "create": false },
          "sds": { "update": false }
        },
        "productFamilies": { "create": false, "update": false },
        "costBookEntries": { "create": false },
        "currentCostSources": { "write": false },
        "priceBookEntries": { "create": false },
        "purchaseOrders": { "documents": { "create": false } }
      }
    }
  }
}

Key lifecycle errors

Authentication fails closed. These errors mean the caller should stop and request a new key or a permission change.

Handling secrets

Never paste the key into a coding agent prompt, Slack, email, logs, or source control. A local agent should read SHELFCYCLE_API_KEY from .env and redact the key from all output.