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.20 contract is reported by GET /me and the OpenAPI document as apiContractVersion or info.version.

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.20",
    "org": { "id": "org-id", "name": "Northstar Chemical" },
    "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", "notes:read", "notes:write", "customers:read"],
      "accessMode": "restricted",
      "storedGrants": ["company-reference:read", "search:read", "notes:read", "notes:write", "customers:read"],
      "effectiveScopes": ["company-reference:read", "search:read", "notes:read", "notes:write", "customers: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": {
      "search": { "viewableTypes": ["customer", "contact", "product", "order", "purchase_order", "location"] },
      "notes": { "create": true, "view": true, "update": true, "viewableSubjectTypes": ["customer", "product"] },
      "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 } },
      "productFamilies": { "view": true, "create": false, "update": false },
      "orders": { "view": false, "changedRecordDiscovery": false, "commercialEconomics": false },
      "purchaseOrders": { "view": false, "changedRecordDiscovery": false, "commercialEconomics": false },
      "reports": { "available": [] },
      "writeReadiness": {
        "notes": { "create": true, "update": true },
        "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 } },
        "productFamilies": { "create": false, "update": 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.