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

# API Keys

> Create and manage scoped API keys for SDK integration and widget embedding.

API keys allow your backend servers to interact with Fluxrate without user authentication. They are scoped to specific operations for security.

## Scopes

| Scope         | Description                                |
| ------------- | ------------------------------------------ |
| `usage.write` | Track usage events, generate widget tokens |
| `usage.read`  | Read usage data                            |

## Creating an API Key

<Tabs>
  <Tab title="Dashboard">
    1. Go to **API Keys** in the sidebar
    2. Click **Create API Key**
    3. Give it a descriptive name (e.g., "Production Backend")
    4. Select required scopes
    5. Click **Create**
    6. **Copy the key immediately** — it's only shown once
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.fluxrate.co/api/v1/api-keys \
      -H "Content-Type: application/json" \
      -H "Cookie: access_token=<token>" \
      -d '{
        "name": "Production Backend",
        "scopes": ["usage.write"]
      }'
    ```

    Response:

    ```json theme={null}
    {
      "id": "...",
      "name": "Production Backend",
      "key": "org_live_abc123xyz...",
      "scopes": ["usage.write"],
      "status": "ACTIVE",
      "created_at": "2025-01-01T00:00:00Z"
    }
    ```
  </Tab>
</Tabs>

<Warning>
  The `key` value is shown **only once** at creation time. If you lose it, delete the key and create a new one.
</Warning>

## Listing API Keys

```bash theme={null}
GET /api/v1/api-keys
```

Note: The key secret is **never** returned in list responses — only the key ID, name, scopes, and status.

## Deleting an API Key

```bash theme={null}
DELETE /api/v1/api-keys/<key_id>
```

Deleted keys are immediately revoked. Any requests using that key will receive a `401 Unauthorized` response.

## Security Best Practices

1. **Least privilege** — Only grant the scopes your integration actually needs
2. **Environment variables** — Store keys in environment variables, never in code
3. **Rotate regularly** — Delete and recreate keys periodically
4. **Per-environment** — Use separate keys for development, staging, and production
5. **Monitor** — Watch for unexpected usage patterns

## API Key Format

Keys follow the format: `org_live_<random>` for production keys.