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

# Authentication

> How to authenticate with the Power Signals API using API keys.

# Authentication

The Power Signals API uses **API key authentication**. Include your key in the `X-API-KEY` header with every request.

```bash theme={null}
curl -H "X-API-KEY: ps_live_abc123..." https://api.powersignals.co.za/api/v1/grid/system-state
```

## Getting an API Key

1. Sign in to your [Power Signals dashboard](https://powersignals.co.za/login/)
2. Navigate to **API Keys**
3. Click **Create New Key** and provide a descriptive name
4. Copy the key immediately — it is only displayed once

<Warning>
  Store your API key securely. Never commit it to version control or expose it in client-side code.
</Warning>

## Using Your API Key

Pass the key in the `X-API-KEY` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-KEY: your_api_key_here" \
    "https://api.powersignals.co.za/api/v1/grid/system-state?start=2026-01-01T00:00:00Z&end=2026-01-02T00:00:00Z"
  ```

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

  headers = {"X-API-KEY": "your_api_key_here"}
  response = requests.get(
      "https://api.powersignals.co.za/api/v1/grid/system-state",
      headers=headers,
      params={"start": "2026-01-01T00:00:00Z", "end": "2026-01-02T00:00:00Z"},
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.powersignals.co.za/api/v1/grid/system-state?start=2026-01-01T00:00:00Z&end=2026-01-02T00:00:00Z",
    { headers: { "X-API-KEY": "your_api_key_here" } }
  );
  ```
</CodeGroup>

## Key Management

### Multiple Keys

You can create multiple API keys for different environments or applications. Each key has:

* **Name** — A label you choose (e.g. "Production", "Staging", "Analytics Pipeline")
* **Prefix** — The first few characters, shown in your dashboard for identification
* **Created date** — When the key was generated
* **Last used** — When the key was last used to make a request

### Revoking Keys

If a key is compromised or no longer needed:

1. Go to **API Keys** in your dashboard
2. Find the key by its prefix or name
3. Click **Revoke**

<Info>
  Revocation is immediate and irreversible. Any requests using the revoked key will receive a `401 Unauthorized` response.
</Info>

## Endpoint Authentication

All endpoints require authentication:

| Endpoint                           | Auth Required |
| ---------------------------------- | :-----------: |
| `GET /api/v1/grid/system-state`    |      Yes      |
| `GET /api/v1/features/grid-stress` |      Yes      |

## Error Responses

If authentication fails, you'll receive:

```json theme={null}
{
  "detail": "Authentication credentials were not provided."
}
```

Or if the key is invalid/revoked:

```json theme={null}
{
  "detail": "Invalid API key."
}
```

## Security Best Practices

* Use environment variables to store your API key
* Create separate keys for development and production
* Rotate keys periodically
* Revoke keys immediately if compromised
* Never share keys between teams — create one per person or service