Authentication

All requests to the Shelfforce API must include a valid API key. Keys are created in the Shelfforce dashboard and sent as a Bearer token in the Authorization header.

API key format

Shelfforce API keys use the following format:

sf_live_<64 hex characters>

For example:

sf_live_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

The sf_live_ prefix identifies the key as a production Shelfforce API key.

Key roles

Each API key is assigned a role that determines which endpoints it can access:

Role	Permissions	Use case
`read`	`GET` endpoints only	Dashboards, reporting integrations, read-only agents
`write`	`GET` + `POST` + `PATCH` endpoints	Image analysis, task creation, field team apps
`admin`	Full access including webhook management and key management	Backend services, infrastructure automation

The admin role is required to create and manage webhooks. Choose the least-privileged role that meets your needs.

Creating API keys

Open API Key settings

Navigate to Settings > API Keys in the Shelfforce dashboard.

Create a new key

Click Create API Key. Provide a descriptive name (e.g., “Production Backend” or “Field App - Read Only”) and select a role.

Copy your key

The full API key is displayed once after creation. Copy it immediately and store it in a secure location such as a secrets manager or environment variable.

API keys are shown only once at creation. If you lose a key, you must revoke it and create a new one.

Using your API key

Include your API key in the Authorization header of every request:

curl https://shelfforce.ai/api/v1/analyses \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

const response = await fetch("https://shelfforce.ai/api/v1/analyses", {
  headers: {
    "Authorization": "Bearer sf_live_a1b2c3d4...",
  },
});

import requests

response = requests.get(
    "https://shelfforce.ai/api/v1/analyses",
    headers={
        "Authorization": "Bearer sf_live_a1b2c3d4...",
    },
)

Requests without a valid Authorization header receive a 401 response:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Missing or invalid Authorization header. Include your API key as: Authorization: Bearer sf_live_..."
  }
}

Key rotation

To rotate an API key without downtime:

Create a new key

Generate a new API key with the same role as the key you are replacing.

Update your application

Deploy the new key to all services and environments that use the old key.

Verify

Confirm that all requests are succeeding with the new key by checking your logs or the API key usage metrics in the dashboard.

Revoke the old key

Once you are confident the new key is in use everywhere, revoke the old key from the API Keys settings page. Revocation is immediate and irreversible.

Security

Shelfforce takes API key security seriously:

Hashed storage — API keys are hashed with SHA-256 before being stored. The plaintext key is never persisted on our servers.
Shown once — Keys are displayed only at the moment of creation. There is no way to retrieve a key after navigating away.
Audit logging — All API key creation, usage, and revocation events are logged and visible in your dashboard.
Instant revocation — Revoking a key takes effect immediately. All in-flight requests using that key will be rejected.

Store API keys in environment variables or a secrets manager. Never hardcode keys in source code, commit them to version control, or include them in client-side bundles.

Best practices

Use separate keys for each environment (development, staging, production).
Assign the minimum required role to each key.
Rotate keys periodically, especially after team member departures.
Monitor key usage in the dashboard and revoke any keys that show unexpected activity.

Getting Started

Core Concepts

Guides

API key format

Key roles

Creating API keys

Using your API key

Key rotation

Security

Best practices

​API key format

​Key roles

​Creating API keys

​Using your API key

​Key rotation

​Security

​Best practices

API key format

Key roles

Creating API keys

Using your API key

Key rotation

Security

Best practices