> ## 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 with the TIC API using API keys or JWT. The same auth model works for the LENS API (v2) and the legacy v1 API.

<Info>
  This page covers the authentication flows shared by both APIs. For **LENS (v2)** specifics — detailed error codes, feature gating, and brute-force protection — see [Authentication in the v2 API](/api-lens/authentication).
</Info>

TIC uses a single authentication model for both the **LENS API (v2)** (`https://lens-api.tic.io`) and the **legacy v1 API** (`https://api.tic.io`). Pick whichever method fits your use case.

| Method                                                  | When to use                                                                                                      |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [API key in querystring](#querystring-authentication)   | Quick experiments and shared snippets. Exposes the key in URLs — **avoid in production**.                        |
| [API key in header](#request-header-authentication)     | The standard for server-to-server integrations.                                                                  |
| [JWT via OTP login](#login-user-and-retrieve-jwt-token) | End-user applications where the call is made on behalf of a logged-in user. Restricted to approved applications. |

## Querystring authentication

Append `key=your_api_key` to the URL.

<Warning>
  The key is visible in browser history, server logs, and proxy logs. Only use this for throwaway experiments.
</Warning>

```bash cURL theme={null}
# LENS API (v2)
curl "https://lens-api.tic.io/search-public/companies?q=the+intelligence+company&query_by=names&key=your_api_key"

# Legacy v1 API
curl "https://api.tic.io/search/companies?q=the+intelligence+company&query_by=names&key=your_api_key"
```

## Request header authentication

Pass the key in the `x-api-key` header. This is the recommended method.

```bash cURL theme={null}
# LENS API (v2)
curl -H "x-api-key: your_api_key" "https://lens-api.tic.io/companies/12345"

# Legacy v1 API
curl -H "x-api-key: your_api_key" "https://api.tic.io/datasets/companies/12345"
```

## Login user and retrieve JWT token

Use this when your application calls the API on behalf of an end user and needs a user-scoped token. This flow is only available to approved applications.

```mermaid theme={null}
flowchart LR
    A[1. POST /login-otp] -- 2. User receives OTP --> B(3. POST /login-otp-validate)
    B --> C{Code valid?}
    C -- Yes --> D[4. JWT token returned]
    C -- No --> F[Retry]
```

### 1. Request a one-time password

POST to `login-otp` with the user's mobile phone (E.164) or email address.

```bash cURL theme={null}
curl https://api.tic.io/ask_for_approval/login-otp \
  -d '{
    "e164MobilePhoneNumber": "+461234567",
    "email": "user-email@domain.tld"
  }'
```

```json Response theme={null}
{
  "userGuid": "DAE48E21-E457-44AB-8DB1-8859E3424179",
  "validationCodeValidUntilUtc": "2024-06-18T12:01:24"
}
```

### 2. User receives the OTP

The code is sent to the user's phone or email and is valid for a short window.

### 3. Validate the OTP

POST the `userGuid` and the code the user received.

```bash cURL theme={null}
curl https://api.tic.io/ask_for_approval/login-otp-validate \
  -d '{
    "userGuid": "DAE48E21-E457-44AB-8DB1-8859E3424179",
    "validationCode": "<received by the user>"
  }'
```

```json Response theme={null}
{
  "userGuid": "DAE48E21-E457-44AB-8DB1-8859E3424179",
  "token": "<JWT Token>",
  "tokenExpiresAtUtc": "2024-07-18T12:02:10"
}
```

### 4. Use the JWT

Send the token as a `Bearer` credential in the `Authorization` header. Works against both APIs.

```bash cURL theme={null}
# LENS API (v2)
curl -H "Authorization: Bearer <JWT Token>" "https://lens-api.tic.io/companies/12345"

# Legacy v1 API
curl -H "Authorization: Bearer <JWT Token>" "https://api.tic.io/datasets/companies/12345"
```