API Keys

Applications sending events to Seq can provide an API key to identify themselves. API keys can be created at the system level (under Settings > API Keys), or for a user's personal access under (username) > API keys.

In addition to granting applications access to the Seq API, API keys can be used to:

• Tag ingested events with properties allowing them to be inspected and filtered easily
• Authenticate log sources to prevent accidental or unauthorized writes
• View the rate of incoming events and raw JSON bytes from a log source
• Filter events on arrival, including by log level, reducing server load in the case of runaway logging
• Notify the log source of the desired logging level in order to reduce network traffic

Creating an API Key

📘

These instructions show the screens for managing system API keys; personal API keys are created and managed identically, but enforce high-entropy token generation (specifying tokens is not permitted for personal API keys).

API keys are listed, and created, in the Data > Ingestion screen within Seq.

Selecting Add API key will request a name and other details of the key. Here, the properties to apply, filter, and logging level to advertise can be specified.

Attached properties

It's a good idea to attach a property to each API key that identifies it. That makes it easier to build signals for the source application that API key belongs to.

Server timestamps

For sources that have skewed clocks, setting the Use server timestamps checkbox will ignore the timestamp attached to ingested events and use the current server time instead. If events are logged in batches this may cause them to receive a later timestamp than they were originally given.

Filter

The Filter edit box will apply a filter to events as they arrive. Only events that match the filter will flow through into the Seq event store.

👍

API key arrival filters can significantly reduce log noise. You can check on the effectiveness of API key filters by comparing "arrived" vs. "ingested" numbers in Data > Storage.

Using the API Key token

When the API key is saved, its token will be displayed. This is supplied to the client logging library as part of the application's configuration, for example with Serilog:

Log.Logger = new LoggerConfiguration()
  .WriteTo.Seq("https://seq.example.com", apiKey: "9fs9V80bjlkgau9adsjH")
  .CreateLogger();

Events arriving from the application will include any applied properties:

👍

How many API keys should I create?

API keys are an easy way to keep track of where events are coming from, and to filter it accordingly.

In general, every distinct application writing to Seq should have its own API key. If the application is deployed in multiple configurations, using a different key for each configuration is also a good idea.

🚧

Avoid frequent duplication of token prefixes

Seq generates API key tokens with an additional four-character prefix or "tag", which remains visible in the Seq UI, and can be useful when debugging ingestion problems. Seq also uses this value to optimized API key lookups in some scenarios.

If you choose to specify API key tokens manually, avoid duplication in the tag part of the API key token (the first four characters).

API keys and permissions

API keys can be assigned a subset of permissions from the following options:

• Ingest - Add events to the event store.
• Read - Query events, dashboards, signals, app instances, etc.
• Write - Write-access to signals, alerts, preferences, etc.
• Project - Access to settings that control data ingestion, storage, dashboarding and alerting.
• Organization - Access to user account settings.
• System - Access to settings related to server configuration.

System API keys can have any of the permissions assigned; personal API keys only provide the permissions held by their owner at the time the key is used.