Authentication

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.

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	Quick experiments and shared snippets. Exposes the key in URLs — avoid in production.
API key in header	The standard for server-to-server integrations.
JWT via OTP login	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.

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

cURL

# 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.

cURL

# 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"

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.

1. Request a one-time password

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

cURL

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

Response

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

cURL

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

Response

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

cURL

# 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"

Technology

Agentic AI

Get Started

Core Datasets

Industry Datasets

Authentication

Querystring authentication

Request header authentication

1. Request a one-time password

2. User receives the OTP

3. Validate the OTP

4. Use the JWT

​Querystring authentication

​Request header authentication

​Login user and retrieve JWT token

​1. Request a one-time password

​2. User receives the OTP

​3. Validate the OTP

​4. Use the JWT

Querystring authentication

Request header authentication

Login user and retrieve JWT token

1. Request a one-time password

2. User receives the OTP

3. Validate the OTP

4. Use the JWT