API Keys

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:

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.

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.