Metrics authentication

https://metrics.toggly.io is the ingest host. It does not accept dashboard OAuth tokens from Team Settings → API Keys.

Create application keys in the Toggly dashboard under the application: Frontend, Backend, and Mobile. Use the type that matches the call.

Backend keys stay on the server

Never ship a Backend application key in a browser, mobile binary you do not control, or public repo. Mint identities from your backend, then pass only the opaque instanceId to the client.

Which key for which call

Call	Host	Key type	How the key is sent	Browser?
Compact telemetry	`POST https://metrics.toggly.io/api/frontend/telemetry`	Frontend or Mobile	JSON body `k`	Yes, if `Origin` is allowlisted
Mint identity	`POST https://metrics.toggly.io/api/frontend/identities`	Backend only	`Authorization` header (raw key or `Bearer`)	No — CORS is disabled
Usage / FeatureStat	`POST https://metrics.toggly.io/api/usage/stats`	Any application key	JSON body `appKey`	Not intended; use an SDK or server
gRPC `Usage.SendStats` / `Metrics.SendMetrics`	`metrics.toggly.io`	Application key in protobuf	Same as the HTTPS FeatureStat packet	No

Trusted .NET and other server SDKs still use gRPC on this host. gRPC is not in the Metrics API Reference OpenAPI document.

Key types

Frontend

Browser-safe. Used by JS and other frontend SDKs for compact telemetry.

Send the key as k in the JSON body, not as Authorization.
Browsers must send an Origin header. If the application has AllowedOrigins set, the origin must match or ingest returns 403. A missing Origin is also 403.
CORS on this endpoint allows POST and OPTIONS only. Rate-limit Retry-After is not exposed on CORS responses.
Do not use a Frontend key to mint identities (that returns 403).

Backend

Secret. Used by your servers.

Mint identities with Authorization: YOUR_BACKEND_KEY or Authorization: Bearer YOUR_BACKEND_KEY.
Frontend and Mobile keys on mint return 403. Unknown keys return 401.
There is no CORS on mint. A browser fetch from docs or your site will fail; that is intentional.

Mobile

Treat like Frontend for compact telemetry (k in the body). Rejected on mint (403), same as Frontend.

Frontend telemetry

Compact JSON. Trailing zeros in feature arrays may be omitted.

{
  "k": "YOUR_FRONTEND_KEY",
  "e": "Production",
  "f": {
    "checkout": {
      "on": [12, 3, 1]
    }
  },
  "m": {
    "page_load_ms": 240
  }
}

Field	Meaning
`k`	Frontend or Mobile application key
`e`	Environment name
`f`	Feature → variant → `[checks, used, viewed]`
`m`	App-level metrics (counters sum, gauges last write)
`i`	Optional minted opaque instance id (preferred when you mint)
`u`	Optional client-asserted identity. Attributed only if the application toggle Accept client-generated identities for metrics is on (default off)

Unknown or expired i is stripped; the packet still returns 202. Do not send a Backend key as k.

curl -X POST https://metrics.toggly.io/api/frontend/telemetry \
  -H "Content-Type: application/json" \
  -H "Origin: https://your-app.example" \
  -d '{"k":"YOUR_FRONTEND_KEY","e":"Production","f":{"checkout":{"on":[1]}}}'

Typical status codes: 202 accepted, 400 invalid body, 403 origin, 404 unknown app or environment, 413 too large, 429 rate limited, 503 backpressure.

Identity mint

Call this only from a backend that holds the Backend key. Pass instanceId to the browser or app for definitions ?i= and telemetry i.

curl -X POST https://metrics.toggly.io/api/frontend/identities \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_BACKEND_KEY" \
  -d '{"identity":"user-42","groups":["beta"],"claims":{"plan":"pro"}}'

Authorization: Bearer YOUR_BACKEND_KEY is also accepted.

200 response:

{
  "identity": "user-42",
  "instanceId": "opaque-token-for-the-client"
}

Keep instanceId secret to that user session. It is not the targeting identity shown in the dashboard.

Status	Meaning
200	Minted or rotated
400	Missing or invalid identity
401	Missing or unknown key
403	Key is not Backend

Usage ingest (FeatureStat JSON)

Same payload as gRPC Usage.SendStats. The key is appKey inside the JSON.

curl -X POST https://metrics.toggly.io/api/usage/stats \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-sdk/1.0.0" \
  -d '{"appKey":"YOUR_APP_KEY","environment":"Production","time":"2026-09-19T18:00:00Z","stats":[]}'

Typical status codes: 200, 400, 404, 429.

OpenAPI spec

Machine-readable spec (CORS-enabled for this docs site):

https://metrics.toggly.io/swagger/v2/swagger.json

Interactive UI: Metrics API Reference.

Which key for which call​

Key types​

Frontend​

Backend​

Mobile​

Frontend telemetry​

Identity mint​

Usage ingest (FeatureStat JSON)​

OpenAPI spec​

Related​