Ingest Tokens

Humio has two kinds of API tokens; Personal API Tokens and Ingest Tokens.

Personal API Token

All users have a Personal API Token, which you can find in your account settings page. This is used for accessing the management API, for example when you create new repositories. These tokens should not be used for sending data to Humio, even though this is strictly possible. For that, you use ingest tokens.

Ingest Tokens

Unlike Personal API Tokens, you cannot use Ingest Tokens to manage Humio. Ingest tokens are a per-repository token that allows you to send data to a specific repository. They are also write-only, meaning you cannot query Humio, log in, or read any data.

Ingest tokens are tied to a repository instead of a user. This provides a better way of managing access control and is more convenient for most use cases.

For example, if a user leaves the organization or project, you do not need to reprovision all agents that send data with a new token. You also don’t have to create fake “Bot” user accounts.

You can manage your ingest tokens in the Settings tab in each repository.

Assigning a Token to a Parser

See how to assign a parser to an ingest token in Assigning Parsers to API Tokens.

Custom Tokens

From Humio 1.19, it is possible for root users to create tokens with a specific string.

It is highly recommended to use automatically generated tokens whenever possible, but custom ingest tokens can be useful in cases where you already have a token in use and want Humio to accept it, or where the log shipper requires tokens in a format that is incompatible with the ones automatically generated by Humio.

Generally, ingest tokens should be sufficiently complex such that they are not easy to guess. When creating custom ingest tokens, it is your responsibility to ensure this.

To use custom tokens, the feature “CustomTokens” must first be enabled. This can be done by making the following GraphQL mutation (see GraphQL documentation page):

javascript
mutation {
    enableFeature(feature: CustomIngestTokens)
}

Once enabled, root users can then create custom tokens via the GraphQL API:

javascript
mutation {
    addIngestToken(
        repositoryName: "sandbox",
        name: "MyIngestToken",
        parser: "kv",
        customToken: "3413c26781c287f289895883e8e45315",
    ) {
        ingestToken {
            name
           token
        }
    }
}