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

# Authentication

> How to authenticate against the LENS API with an x-api-key header, how plan-feature gating works, and the full 401/403 error reference.

All LENS API requests require an API key passed via the `x-api-key` header.

For a general overview of authentication flows (querystring, header, OTP + JWT) that apply to **both** APIs, see [Authentication](/authentication). This page focuses on the LENS-specific key management, feature gating, and error model.

## Example

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/search-public/companies?q=Volvo&query_by=names.nameOrIdentifier"
```

## Managing API keys

API keys are managed through the TIC Lens web application under **Settings → API Keys**. Each key is tied to a team and inherits the team's subscription plan and features.

## Key properties

| Property         | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| Scopes           | Comma-separated access scopes controlling which operations the key can perform |
| Valid until      | Optional expiry date after which the key stops working                         |
| Blocked until    | Temporary block set by an administrator                                        |
| Monthly limit    | Maximum requests per calendar month                                            |
| Per-minute limit | Maximum requests per sliding 60-second window                                  |
| IP limit         | Maximum number of distinct IP addresses that can use the key per month         |

## Subscription and features

Your API key is linked to a team subscription. Endpoints are gated by plan features (e.g. `pro`, `max`, `enterprise`). If your plan does not include the required feature, the endpoint returns `403` with the missing feature name:

```json theme={null}
{
  "status": 403,
  "title": "Feature Not Available",
  "detail": "Your subscription does not include the 'enterprise' feature.",
  "code": "feature_required",
  "features": ["enterprise"]
}
```

If the team's subscription has expired, all endpoints return `403`:

```json theme={null}
{
  "status": 403,
  "title": "Subscription Expired",
  "detail": "Your team's subscription has expired. Please renew to continue.",
  "code": "subscription_expired"
}
```

## Brute-force protection

After **10 failed attempts** within a 15-minute window, the IP is blocked for **15 minutes**. All requests from that IP will return `401` until the block expires.

The API tracks failed authentication attempts per IP address. During a block:

```json theme={null}
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Too many failed authentication attempts. Please try again later.",
  "code": "ip_blocked"
}
```

## Endpoint access

API keys can only access endpoints marked as public API endpoints. Attempting to call an internal endpoint returns `403`:

```json theme={null}
{
  "status": 403,
  "title": "Endpoint Not Available",
  "detail": "This endpoint is not available for API key authentication.",
  "code": "endpoint_not_available"
}
```

## Request validation

Requests containing SQL injection, XSS, or path traversal patterns are blocked with `400 Bad Request`. All requests are inspected for malicious patterns before reaching the application.

## Error reference

All error responses use the RFC 7807 Problem Details format with an additional `code` field.

| Status | Code                     | Cause                                                                    |
| ------ | ------------------------ | ------------------------------------------------------------------------ |
| `400`  | —                        | Request blocked by input validation (SQL injection, XSS, path traversal) |
| `401`  | `missing_token`          | No `x-api-key` header provided                                           |
| `401`  | `invalid_api_key`        | API key not found                                                        |
| `401`  | `ip_blocked`             | Too many failed attempts from this IP (15-minute cooldown)               |
| `403`  | `api_key_blocked`        | Key has been temporarily blocked by an administrator                     |
| `403`  | `api_key_expired`        | Key has passed its `ValidUntil` date                                     |
| `403`  | `subscription_required`  | Team has no active subscription                                          |
| `403`  | `subscription_expired`   | Team subscription has expired                                            |
| `403`  | `feature_required`       | Endpoint requires a plan feature the team doesn't have                   |
| `403`  | `endpoint_not_available` | Endpoint is not available for API key access                             |
| `429`  | `rate_limit_exceeded`    | Rate limit exceeded (see [Rate limits](/api-lens/rate-limits))           |