# API Keys

## Overview

API keys allow you to authenticate with the Tailglow API programmatically, without a user session. They are useful for backend integrations, CI/CD pipelines, and scripts that need to interact with Tailglow on behalf of your team.

API keys are separate from **ingest keys**. Ingest keys are used to send data to your ingest servers, while API keys are used to interact with the Tailglow management API (e.g., creating projects, managing views, querying metrics).

## Creating an API Key

To create a new API key:

1. Navigate to your **Team Settings**.
2. Select the **API Keys** tab.
3. Click the plus button labeled **Create an API key**.
4. Configure the following fields:
   - **Name**: A descriptive name for the key (2-60 characters).
   - **Quick fill**: Optionally start with **Common** or **Full access**, or click **Clear** to remove all selected scopes.
   - **Scopes**: Choose which permissions the key should have. You can only assign permissions that you yourself have.
5. Click **Create API Key**.

The API key will be displayed once after creation. Copy and store it securely -- you will not be able to see it again.

## Using an API Key

Include the API key in the `Authorization` header of your requests:

```bash
curl -X GET "https://api.tailglow.io/v1/projects" \
  -H "Authorization: Bearer tg_api_your_api_key"
```

You can also create a key from the terminal with `tglow login --method api-key`: approve it in the browser, choose its permissions, and the CLI stores it. See [CLI](/guides/cli#authenticating).

## Key Properties

- **last4**: The last 4 characters of the key, for identification.
- **scopes**: The permissions assigned to the key.
- **last_used_at**: When the key last authenticated a request, accurate to five minutes.

## Managing API Keys

From the **API Keys** tab in your team settings, you can:

- **View all keys**: See each key's name, last 4 characters, and when it was last used. A key created before Tailglow began recording use shows **No recorded use** until its next request.
- **Update a key**: Change the name or scopes of an existing key.
- **Delete a key**: Permanently revoke a key. This takes effect immediately.

## Security

- API keys inherit the scopes you assign to them. Follow the principle of least privilege -- only grant the permissions the key needs.
- Quick-fill choices only preselect scopes in the creation form. Review them before saving and remove any
  permission the integration does not need.
- The available quick-fill choices are **Common** and **Full access**. **Clear** removes all scopes.
- Unlike human roles, API keys do not require `projects:read`. A key may be limited to one narrow
  operation.
- Rotate keys periodically by creating a new key, updating your integrations, and deleting the old one.
- Never commit API keys to version control. Use environment variables or a secrets manager.