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

# Authentication

> API key management, authentication methods, and security best practices

All API endpoints (except `/v1/health`) require authentication. The Appeeky API uses API keys to identify and authorize requests.

***

## Get Your API Key

Create a free account on the **Appeeky Dashboard** to get your API key with **100 monthly credits**:

<Card icon="key" href="https://dashboard.appeeky.com" title="Create Your Account">
  Sign up with email or GitHub — your API key is generated instantly.
</Card>

<Warning>
  Save your API key immediately. It is displayed **only once** during creation. The key is stored as a SHA-256 hash in our database and cannot be retrieved later. You can regenerate a new key from the dashboard at any time.
</Warning>

***

## Authentication Methods

The API supports two ways to pass your API key.

### Method 1: X-API-Key Header (Recommended)

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

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/apps/1617391485?country=us" \
    -H "X-API-Key: apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/apps/1617391485?country=us",
    {
      headers: {
        "X-API-Key": "apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab",
      },
    }
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/apps/1617391485",
      params={"country": "us"},
      headers={"X-API-Key": "apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

### Method 2: Authorization Bearer Header

Alternatively, use the standard `Authorization: Bearer` header:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/apps/1617391485?country=us" \
    -H "Authorization: Bearer apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/apps/1617391485?country=us",
    {
      headers: {
        Authorization: "Bearer apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab",
      },
    }
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/apps/1617391485",
      params={"country": "us"},
      headers={"Authorization": "Bearer apk_a1b2c3d4e5f6789012345678abcdef90abcdef1234567890abcdef1234567890ab"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

<Tip>
  Both methods are equivalent. Use whichever fits your HTTP client or framework. If both headers are present, `X-API-Key` takes priority.
</Tip>

***

## Check Your Usage

Monitor your credit consumption via the API or the [dashboard](https://dashboard.appeeky.com/dashboard/usage):

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/auth/usage" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch("https://api.appeeky.com/v1/auth/usage", {
    headers: { "X-API-Key": "YOUR_API_KEY" },
  });
  const { data } = await res.json();
  console.log(`${data.used}/${data.monthlyCredits} credits used`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/auth/usage",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  print(f'{data["used"]}/{data["monthlyCredits"]} credits used')
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "plan": "free",
    "monthlyCredits": 100,
    "used": 47,
    "remaining": 53,
    "resetDate": "2026-03-01T00:00:00.000Z",
    "usageByEndpoint": [
      { "endpoint": "GET /apps/:id", "totalCredits": 20, "requestCount": 10 },
      { "endpoint": "GET /apps/:id/intelligence", "totalCredits": 25, "requestCount": 5 },
      { "endpoint": "GET /search", "totalCredits": 2, "requestCount": 2 }
    ]
  }
}
```

***

## Manage Your Account

Use the **Appeeky Dashboard** to manage your API key, view usage, and upgrade your plan:

| Action                 | Where                                                      |
| ---------------------- | ---------------------------------------------------------- |
| View & copy API key    | [Dashboard](https://dashboard.appeeky.com/dashboard)       |
| Regenerate API key     | [Dashboard](https://dashboard.appeeky.com/dashboard)       |
| View usage breakdown   | [Usage](https://dashboard.appeeky.com/dashboard/usage)     |
| Upgrade or manage plan | [Billing](https://dashboard.appeeky.com/dashboard/billing) |

***

## Error Responses

| Status | Code                  | When                                   |
| ------ | --------------------- | -------------------------------------- |
| 401    | `MISSING_API_KEY`     | No API key provided in request headers |
| 401    | `INVALID_API_KEY`     | Key is invalid, inactive, or revoked   |
| 429    | `RATE_LIMIT_EXCEEDED` | Monthly credit limit reached           |

**Example error response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it in the X-API-Key header or Authorization: Bearer header."
  }
}
```