# Ingest Key

## Getting Your Key

Your ingest key is located in your source settings. Select a project, open **Settings**, choose the **Sources** tab, and click the edit button for a source. In the source drawer, select the **Ingest** tab. The **Ingest Keys** section lets you view and manage the source's keys. Each source can have multiple ingest keys.

## Prefix

Your ingest key always begins with the prefix `tg_ingest_`.

## Usage

### Query Parameter (Recommended)

The simplest way to authenticate is by including your ingest key as a `key` query parameter in the URL. This works across all platforms -- browsers, backends, and mobile apps.

```bash
curl -X POST "https://us11.ingest.tailglow.io/prj_xxx?key=tg_ingest_123" \
  -H "Content-Type: text/plain" \
  -d '{"records": []}' # Your records here
```

Replace the URL with your project's ingest endpoint, found in your source settings.

Even though the payload is JSON, setting `Content-Type: text/plain` is safe because the ingest server auto-detects the format. For browser-based clients, this is especially important: `text/plain` is a [simple content type](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests), so browsers skip the CORS preflight OPTIONS request entirely, sending one request instead of two.

This method also works with `navigator.sendBeacon`, which does not support custom headers:

```javascript
navigator.sendBeacon(
  "https://us11.ingest.tailglow.io/prj_xxx?key=tg_ingest_123",
  JSON.stringify({ event: "page_view", path: "/home" })
);
```

### Authorization Header

You can also include your ingest key in the `Authorization` header using the `Bearer` or `Key` prefix:

```bash
curl -X POST https://us11.ingest.tailglow.io/prj_xxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Key tg_ingest_123" \
  -d '{"records": []}' # Your records here
```

Note that from browsers, using a custom `Authorization` header with `Content-Type: application/json` will trigger a CORS preflight request, doubling the number of requests.

## Security

Your ingest key has write-only access to your ingest server. While it's important to keep this key private, it's acceptable to include it in frontend code if you're using the ingest server for frontend metrics and analytics.

## Managing Your Keys

Each source can have multiple ingest keys. You can create new keys and delete old ones as needed from your source settings. When you need to rotate a key, simply create a new one, update your services to use it, and then delete the old key.

## Key and Team Status

An ingest key works only when its team status also permits ingestion:

- **Active team**: An active key on an active team works normally.
- **Delinquent team**: For a non-Enterprise team, an uncollectible or later-unpaid invoice can make the team delinquent. Active ingest keys are then disabled until the payment issue is resolved. A single failed payment attempt does not by itself apply this state.
- **Restricted team**: The team is read-only and ingestion is disabled until the restriction is resolved.
- **Blocked team**: The team cannot be accessed and ingestion is disabled. Contact support to resolve this.

An ingest request is accepted only when both the key and its team are active. If the team becomes `delinquent`, `restricted`, or `blocked`, the key stops accepting data. Update your payment information or contact support as appropriate to restore access.