> For the complete documentation index, see [llms.txt](https://docs.luciq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luciq.ai/references/api-access/authentication.md).

# Authentication

Create and manage Luciq Query API keys, see which data each key can read, and send your first authenticated request with a bearer token.

#### Create an API Key <a href="#create-an-api-key" id="create-an-api-key"></a>

Owners and admins create keys in the dashboard, under **Settings › Company › Connections › API keys**.

When you create a key, choose:

* **A name**, so your team knows what the key is for
* **An expiration**: 7, 30, or 90 days, a custom date, or never
* **The applications**: specific ones, or all applications, including apps added later
* **The data types** the key can read (see below)

Your key starts with `lq_`. It is shown once, so store it somewhere safe. After that, the dashboard shows only its last four characters, for example `lq_••••abcd`.

#### Data types and entities <a href="#data-types-and-entities" id="data-types-and-entities"></a>

Each data type gives the key access to one or more entities.

| Data type       | Entity             | What it holds                                            |
| --------------- | ------------------ | -------------------------------------------------------- |
| Crashes         | `crashes`          | Crash occurrences, grouped by crash number.              |
| Crashes         | `sessions`         | App sessions, with crash-free, ANR, and Apdex metrics.   |
| Bug reports     | `bugs`             | Bug reports from your users.                             |
| App performance | `networks`         | Network requests, with failure rates and response times. |
| App performance | `launches`         | App launches and their durations.                        |
| App performance | `screen_loading`   | How long screens take to load.                           |
| App performance | `screen_rendering` | Slow and frozen frames on each screen.                   |
| App performance | `flows`            | User flows, with completion and drop-off rates.          |
| App performance | `spans`            | The spans inside one parent group, such as one flow.     |

`spans` has no data type of its own. It follows the data type of its parent, App performance. A `spans` query reads the data of the parent entity that its `parent` condition names. So the key must cover that entity:

* A key with the App performance data type covers all five parents.
* A key that covers only some App performance entities can query spans for those parents only. For example, a key that covers `flows` and `networks` can query spans with `parent` `flows` or `networks`. With `parent` `launches`, the request returns `403 forbidden`, and `details.entity` is `launches`.
* `GET /v1/entities` lists `spans` when the key covers at least one parent.

The exact columns, metrics, and operators for each entity are in `GET /v1/entities`.

A key request that names an unknown entity is rejected with `422` and the message `Unknown entities: …`.

#### Manage your keys <a href="#manage-your-keys" id="manage-your-keys"></a>

Each key has one of these statuses:

* **Active**: the key works.
* **Expiring soon**: the key expires within 7 days.
* **Expired**: the key has passed its expiration. Requests return `401 unauthorized` with `details.reason: "key_expired"`.
* **Revoked**: the key was revoked and no longer works.

To revoke a key, open the same page and revoke it. Revoking takes effect immediately.

**Good to know about keys:**

* **Keys belong to your company, not a person.** Your integrations keep working when the teammate who created the key leaves.
* **Keys are scoped.** Each key covers specific applications and data types. A request outside that scope returns `403 forbidden` and names the missing scope.
* **Revoke a leaked key at once.** Then create a new one on the same page.

***

#### Quickstart <a href="#quickstart" id="quickstart"></a>

**1. Authenticate.** Send your key in the `Authorization` header on every request:

```http
Authorization: Bearer lq_your_key_here
Content-Type: application/json
```

2. **Run your first query (Example: Daily Crash Free Session in the last 7 days)**

{% tabs %}
{% tab title="Curl" %}

```bash
curl -s https://api.luciq.ai/v1/query \
  -H "Authorization: Bearer $LUCIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "application": "my-application",
  "environment": "production",
  "entity": "sessions",
  "select": [
    {
      "metric": "crash_free_sessions",
      "as": "cfs"
    }
  ],
  "group_by": [
    {
      "time_bucket": "day"
    }
  ],
  "time_range": {
    "last": "7d"
  }
}'

```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

resp = requests.post(
    "https://api.luciq.ai/v1/query",
    headers={"Authorization": f"Bearer {os.environ['LUCIQ_API_KEY']}"},
    json={
        "application": "my-application",
        "environment": "production",
        "entity": "sessions",
        "select": [
            {
                "metric": "crash_free_sessions",
                "as": "cfs"
            }
        ],
        "group_by": [
            {
                "time_bucket": "day"
            }
        ],
        "time_range": {
            "last": "7d"
        }
    },
)
resp.raise_for_status()
data = resp.json()
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

uri = URI("https://api.luciq.ai/v1/query")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV["LUCIQ_API_KEY"]}"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "application": "my-application",
    "environment": "production",
    "entity": "sessions",
    "select": [
      {
        "metric": "crash_free_sessions",
        "as": "cfs"
      }
    ],
    "group_by": [
      {
        "time_bucket": "day"
      }
    ],
    "time_range": {
      "last": "7d"
    }
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const resp = await fetch("https://api.luciq.ai/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LUCIQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "application": "my-application",
    "environment": "production",
    "entity": "sessions",
    "select": [
      {
        "metric": "crash_free_sessions",
        "as": "cfs"
      }
    ],
    "group_by": [
      {
        "time_bucket": "day"
      }
    ],
    "time_range": {
      "last": "7d"
    }
  }),
});
const data = await resp.json();
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.luciq.ai/references/api-access/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
