# API Authentication

The API Settings page lets workspace admins control who can call your public endpoints and what data each key can send.

| API             | Purpose                                                                              |
| --------------- | ------------------------------------------------------------------------------------ |
| Integration API | <p>Ingest events / profile updates </p><p>Read profiles </p><p>Trigger workflows</p> |
| Metrics API     | Run pre‑defined metric queries or ad‑hoc SQL via HTTPS                               |

## 1 · Access Control by IP

Every key supports an allow‑list:

* Anywhere – key will work from any source IP (default).
* Specific locations – supply one or more static IPv4/IPv6 addresses (or /32 sub‑nets).
  * Click Add IP address, enter IP and optional description, Save.
  * Remove via the red “Remove” link next to the row.

If the caller’s IP is not on the list, the request returns 403 Forbidden.

## 2. Integration  API Key Scopes

### **2.1 Write‑Only Key**

*Can only POST data.* Ideal for frontend applications or backend collectors.

### **2.2 Read & Write Key**

Full CRUD—needed for operations that fetch profile information.

### **2.3 Allowed Profile Events**

Limit which profile events can be sent with this key.

| Option                  | Behaviour                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| All Profile Events      | No restriction.                                                                                                                |
| Specific Profile Events | Toggle chips for the exact event names you wish to allow (e.g. email\_verified, login). Any disallowed event will be rejected. |

## 3. Metrics API Security

The Metrics API is authenticated using a Client Secret and API Key. You can use these to generate a short-lived Access Token which can then be used for subsequent calls to the API.

Never use the Metrics API directly on the frontend. Always proxy the data you are after via your backend so that you do not expose the API Keys.

| Setting             | Description                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| Cache TTL (minutes) | Server‑side cache for query results (min 5 min). Increase to reduce database load in dashboards.  |
| Access Control      | Same “Anywhere / Specific locations” IP allow‑list as above. Only one key exists for Metrics API. |

## 4. Best Practices

* Use the Integration APIs Read & Write Key on your backend for user events tracking associated with key business reporting or workflow triggers
* For any integration on the frontend, use only the Write-Only Key
* Scope user events on public keys to the absolute minimum
* Never use the Metrics API directly on the frontend. Always proxy the data you are after via your backend so that you do not expose the API Keys
* Limit IP Access for the Integration API Read & Write Key as well as the Metrics API


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://userflux.gitbook.io/userflux-docs/security/api-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.