Authentication

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

Example

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 min 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)

Introduction

Rate Limits