Skip to main content
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:
RolePermissionsUse case
readGET endpoints onlyDashboards, reporting integrations, read-only agents
writeGET + POST + PATCH endpointsImage analysis, task creation, field team apps
adminFull access including webhook management and key managementBackend 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

1

Open API Key settings

Navigate to Settings > API Keys in the Shelfforce dashboard.
2

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.
3

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..."
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:
1

Create a new key

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

Update your application

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

Verify

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

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.