> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelfforce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create and manage API keys to authenticate requests to the Shelfforce API.

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          |

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

## Creating API keys

<Steps>
  <Step title="Open API Key settings">
    Navigate to [Settings > API Keys](https://shelfforce.ai/home/developers) in the Shelfforce dashboard.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Warning>
      API keys are shown only once at creation. If you lose a key, you must revoke it and create a new one.
    </Warning>
  </Step>
</Steps>

## Using your API key

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

<CodeGroup>
  ```bash curl theme={null}
  curl https://shelfforce.ai/api/v1/analyses \
    -H "Authorization: Bearer sf_live_a1b2c3d4..."
  ```

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

  ```python Python theme={null}
  import requests

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

Requests without a valid `Authorization` header receive a `401` response:

```json theme={null}
{
  "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:

<Steps>
  <Step title="Create a new key">
    Generate a new API key with the same role as the key you are replacing.
  </Step>

  <Step title="Update your application">
    Deploy the new key to all services and environments that use the old key.
  </Step>

  <Step title="Verify">
    Confirm that all requests are succeeding with the new key by checking your logs or the API key usage metrics in the dashboard.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Tip>
  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.
</Tip>

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