Authentication

Every request to xScaler, whether writing metrics or querying them, requires two HTTP headers.

Required headers

Authorization: Bearer <token>
X-Scope-OrgID: <tenant-id>

Header	Purpose
Authorization: Bearer <token>	Authenticates the caller. The token must be a valid API token issued from the xScaler dashboard.
X-Scope-OrgID: <tenant-id>	Selects the tenant data namespace. This is the tenant isolation header: without it the backend cannot route the request to the correct data store.

Where the Bearer prefix goes

Some clients want the raw token, others the full Bearer <token> string. Pasting Bearer into a raw-token field returns 401 invalid token. So does leaving it out where the client expects it.

Client	Field	Value to paste
curl / raw HTTP	Authorization header	Bearer <token>
Prometheus	authorization.credentials	<token>: raw, Prometheus adds Bearer
Grafana Alloy	authorization.credentials	<token>: raw, Alloy adds Bearer
OpenTelemetry Collector	headers.Authorization	Bearer <token>
Grafana data source	Authorization HTTP header	Bearer <token>

:::danger Both headers are mandatory There are no exceptions. Every remote_write and every query must include both headers. A missing or mismatched X-Scope-OrgID returns 401 (x-scope-orgid mismatch). A missing or invalid Authorization also returns 401. :::

Example: curl

curl "https://euw1-01.m.xscalerlabs.com/api/v1/query" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "X-Scope-OrgID: my-org-123" \
  --data-urlencode 'query=up'

---

Where to find your credentials

1. Log in to the xScaler dashboard at xscalerlabs.com.
2. Navigate to Settings → API Tokens.
3. Note your Tenant ID (the value for X-Scope-OrgID).
4. Create or copy an existing API token (the value for the Bearer credential).

---

Token scopes

Scope	Allowed operations
write	Ingest metrics via remote_write or OTLP. Cannot query.
read	Query via the Prometheus HTTP API. Cannot write.
read+write	Both ingest and query. Suitable for integrated clients such as Grafana Agent or Alloy.

Give each client the narrowest scope it needs. A Prometheus instance that only ships metrics takes a write token.

---

Zero-downtime token rotation

Rotating a token without dropping metrics or queries:

1. Generate a new token in the dashboard with the same scope as the existing token.
2. Update all clients (Prometheus configs, Alloy configs, collector configs, Grafana data sources) to use the new token.
3. Verify traffic. Watch your ingest dashboards and confirm metrics continue to arrive.
4. Delete the old token once traffic from the old token has dropped to zero.

Do not delete the old token before step 3. There may be in-flight remote_write batches that still carry it.

---

Error reference

HTTP Code	Meaning	Common cause
401	Missing or mismatched X-Scope-OrgID header (x-scope-orgid mismatch)	Header omitted, or its value does not match the token's tenant
401	Missing or invalid Authorization header	Token absent, expired, or malformed
403	Token has insufficient scope for the operation	Write-only token used for a query, or vice versa
429	Rate limit exceeded	Too many requests; reduce ingest rate or shard count