Authentication

Authenticate with a bearer API key. Verify the org, scopes, and acting user 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

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, scopes, and acting user.

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

{
  "data": {
    "apiVersion": "v1",
    "org": { "id": "org-id", "name": "Northstar Chemical" },
    "key": {
      "id": "api-key-id",
      "name": "Email notes automation",
      "purpose": "Workflow for creating notes from approved emails",
      "preview": "sk_...abcd",
      "scopes": ["search:read", "notes:write", "contacts:create", "contacts:update"],
      "expiresAt": null
    },
    "actor": { "type": "user", "id": "user-id", "displayName": "Jordan Buyer" },
    "provenance": { "apiKeyId": "api-key-id", "purpose": "Workflow for creating notes from approved emails" }
  }
}

Guardrail

If the org, actor, or scopes are not what the workflow expects, stop before any search or write.

Key lifecycle errors

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

Code	Meaning
`invalid_api_key`	Missing, malformed, unknown, or ambiguous bearer token.
`api_key_revoked`	The key was revoked.
`api_key_expired`	The key is past its expiry.
`api_actor_inactive`	The issued-to user no longer belongs to the org.

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.