Skip to content

Table Access Tokens

The HTTP Stream API supports optional, per-table access tokens to limit which clients can stream data into a table.

Network-layer controls and authorization are enforced before the HTTP Stream API checks this application-layer access control.

By default, the streaming API doesn't require clients to supply a table access token.

Don't confuse table access tokens with OAuth Bearer tokens

See authorization tokens issued to user and service accounts.

Require table access tokens⚓︎

The stream field of a table's [table settings][table settings] contains the configurable fields:

Field Default Description
token_auth_enabled false Boolean. If true, enforce token-based authentication for the table.
token_list [] An array of strings. These are valid tokens.

When token_auth_enabled is true, the ingestion system checks requests for a valid token.

A token is any arbitrary string. The token list is an array to allow for easy token rotations and concurrent use of multiple tokens supporting different client applications.

Clients must present a token either in the token HTTP query parameter or in the X-Hdx-Token HTTP header.

Streaming requests with a token matching any in the token_list are allowed. For all other requests, the ingestion API returns an HTTP 403.

Token list restrictions

Accepts any number of Unicode strings with no restrictions on characters or length.

An empty token_list ([]) or null is also permitted. An empty token list is equivalent to token_auth_enabled: false.

Configure⚓︎

Configure a table with these steps:

  1. Set token_auth_enabled to true in the stream settings of the table.
  2. Set token_list to an array of tokens.

Example⚓︎

1
2
3
4
5
6
7
8
"settings": {
  ...
  "stream": {
    "token_auth_enabled": true,
    "token_list": ['token1', 'token2']
  }
  ...
}

Observability⚓︎

Valid requests using any acceptable token are counted in metric http_source_request_count.

Requests failing to present an acceptable token are counted in metric http_source_request_error_count{status_code="403"}. This shows rejected requests.

Send table access tokens with streaming requests⚓︎

When token_auth_enabled is true, clients must send tokens using either:

  • HTTP header X-Hdx-Token (recommended)
  • HTTP query parameter https://hostname.hydrolix.live/ingest/event?token=token1

When passing a token using query parameters, always URL encode your tokens or generate tokens without special characters.

Protect table access tokens from sniffing by connecting to the HTTP Stream API over TLS and preferring to transmit them in the X-Hdx-Token HTTP header.