Skip to Content
segment

βš™οΈ Configuration

Where segment finds its token, region and timeout, and where the config file lives.

The token

segment needs a Segment Public API token, not the legacy Config API token. They are separate credentials, and a Config API token fails with a 401 or 403 on every call.

Create one in the Segment dashboard under Settings β†’ Access Management β†’ Tokens β†’ +Create Token, and choose Public API token.

Precedence

Each value is resolved independently, first match wins:

Setting1. Flag2. Environment3. Config fileDefault
Token--tokenSEGMENT_API_TOKENtokennone
Region--regionSEGMENT_API_REGIONregionus
Timeout--timeout <ms>SEGMENT_TIMEOUTnot stored15000 ms

An empty environment variable counts as unset. The region accepts us or eu in any case; anything else is an error.

The interactive browser reads the environment and the config file only, so give it its token with SEGMENT_API_TOKEN or segment config set rather than --token.

Regions

RegionAPI host
ushttps://api.segmentapis.com
euhttps://eu1.api.segmentapis.com

The config file

Location: $XDG_CONFIG_HOME/segment-cli/config.json, falling back to ~/.config/segment-cli/config.json.

Write it with config set, which merges into whatever is already there:

segment config set --token tkn_example --region eu

The file is plain JSON:

{
  "token": "tkn_example",
  "region": "eu"
}

Check what is actually in effect, with the token masked to its first and last four characters:

segment config show

Errors worth knowing

StatusMessage ends withUsually means
401check SEGMENT_API_TOKENWrong or legacy token
403the token may lack the required workspace permissionToken scope is too narrow

With no token found anywhere, commands stop with a message listing the three ways to supply one.