> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/en/api-reference/public-api/authentication.md).

# Authentication

## Getting Started

Follow these steps to get your API key and start making requests to Alpha Lenz API.

### Step 1: Create an Account

1. Sign up at <https://alpha-lenz.com>
2. Verify your email address
3. Log in to your dashboard

### Step 2: Generate Your API Key

1. Navigate to **Settings** > **API Keys** in your dashboard
2. Click the **"Create New API Key"** button
3. Give your API key a descriptive name (e.g., "My Production Key")
4. Click **"Create"**

> **⚠️ Important:** Your API key will only be displayed once. Make sure to copy and save it in a secure location immediately. If you lose it, you'll need to create a new key.

### Step 3: Make Your First API Call

Include your API key in the `X-API-Key` header:

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies" \
     -H "X-API-Key: ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
```

**Example Response:**

```json
{
  "data": [
    {
      "company_id": "KR7005930003",
      "company_name": "Samsung Electronics",
      "ticker": "005930"
    }
  ]
}
```

### Step 4: Integrate into Your Application

**Python Example:**

```python
import requests

API_KEY = "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
BASE_URL = "https://api.alpha-lenz.com/api/public/v1"

headers = {
    "X-API-Key": API_KEY
}

response = requests.get(f"{BASE_URL}/financial/companies", headers=headers)
companies = response.json()
```

**JavaScript Example:**

```javascript
const API_KEY = 'ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456';
const BASE_URL = 'https://api.alpha-lenz.com/api/public/v1';

const response = await fetch(`${BASE_URL}/financial/companies`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const companies = await response.json();
```

## API Key Management

### Creating API Keys Programmatically

You can also create API keys programmatically using the API:

**Endpoint:** `POST /api/v1/api-keys`

**Headers:**

```
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```

**Request Body:**

```json
{
  "name": "My Production Key",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "rate_limit": 2000,
  "rate_period": 3600
}
```

**Response:**

```json
{
  "id": 1,
  "name": "My Production Key",
  "key": "ak_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "key_prefix": "ak_aBcDeFgH",
  "scopes": ["read:financial", "read:stock"],
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Viewing Your API Keys

Navigate to the **API Keys** section in your dashboard to:

* View all your active API keys (only the prefix is shown for security)
* Check when each key was created and last used
* See the current status (Active/Revoked)
* Monitor usage and rate limits

### Revoking API Keys

If your API key is compromised or no longer needed:

1. Go to **Settings** > **API Keys**
2. Find the key you want to revoke
3. Click the **"Revoke"** button
4. Confirm the action

Revoked keys cannot be restored. You'll need to create a new key if needed.

## Rate Limiting

Default: **1,000 requests per hour**

Rate limits are enforced per API key. When exceeded:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "detail": "Rate limit exceeded"
}
```

### Custom Rate Limits

You can set custom rate limits when creating an API key:

* `rate_limit`: Number of requests allowed
* `rate_period`: Time period in seconds (60-86400)

If you need higher limits, please contact us via chatbot.