Why there are two
They protect different things and fail differently. A license key lives in your infrastructure — in a collector config, a Kubernetes Secret, a container’s environment. It is long-lived by necessity: a credential that expired every 30 minutes would stop your telemetry every 30 minutes. It can write data and can do nothing else. If it leaks, an attacker can send you junk telemetry; they cannot read your data, change your alerts or see your users. A session lives in a browser. It represents a person, carries that person’s role, and can read and change everything they are permitted to. It is deliberately short-lived, because the damage from a stolen one is much larger. Separating them is what makes it safe to paste a license key into a Helm values file. Merging them is what makes it unsafe.The two credentials
License key
Sends telemetry. Format
oiq_ + 32 hex characters. Never expires; valid
until revoked. Belongs to your whole organization.Session
Uses the product. Issued by signing in. Lasts 30 minutes and refreshes
while you are active. Belongs to one person and carries their role.
”Where do I get an API key?”
There is no separate API key. This is the single most common question about aiAxonIQ authentication, and the honest answer is that the thing people are usually looking for is the license key above. The naming is genuinely confusing, and it is worth being explicit about why:- If you want to send telemetry — logs, metrics, traces, Prometheus
remote-write — the credential is the license key. Some parts of the
product and its API refer to these as API keys; they are the same object.
Settings → API keysis where they live — the interface uses that name, and it is the same object. - If you want to read data or drive the product programmatically, there is
no long-lived token to mint today. You authenticate the same way the dashboard
does: sign in, then send the resulting session as
Authorization: Bearer <token>. That session expires in 30 minutes.
A long-lived, scoped token for programmatic API access does not exist yet.
Where you need automation now, the session-based path above works; treat the
30-minute expiry as a real constraint on script design rather than something
to work around by storing a password.
Using a license key
Send it as a header on every ingest request:Authorization header:
X-License-Key wins.
With an OpenTelemetry SDK, the standard variable sets the header for you:
x-license-key.
Roles
Your session carries a role, which decides what you can change.
The one that catches people out: minting a license key requires Admin.
Anyone signed in can see the key list — names, prefixes, creation and last-used
times — but not the key material, and not the create button.
One-time email codes
A code sent to your email address and exchanged for a session — useful where you would rather not hand out passwords. Two behaviours are worth knowing because they look like bugs:Requesting a code always answers success, with the same body, whether or
not the address belongs to an account. That is what stops the endpoint being
used to discover who has an account. A code is only actually sent if the
address could sign in.Every code failure answers identically. Wrong code, expired code and
already-used code are indistinguishable from outside, for the same reason.
If a code is not working, request a fresh one rather than trying to interpret
the error.
Signing out everywhere
Signing out everywhere is genuinely everywhere. It advances a counter
that invalidates previously-issued tokens, so a token that had been captured
stops working even though nothing about it changed. This is the action to
take if you think a session has been compromised.
Switching organizations
If you belong to more than one organization, switching mints a new session rather than editing the current one — so a token captured while you were in one organization cannot follow you into another. Your role is per organization: Owner in one and Viewer in another is normal. See Organizations and multi-tenancy.Verify
Confirm you have a working session:400 here proves the key was accepted and only the payload was rejected:
401 instead means the key was not accepted. A 404 means $OIQ_ENDPOINT is
wrong — see Endpoints and errors.
Troubleshooting
401 on every service at once, with a key I did not change
401 on every service at once, with a key I did not change
Far more likely to be a validation outage than a credential problem. When the
receiver cannot reach the service that validates keys, it fails closed and
returns the same
401 as a genuinely invalid key.Check $OIQ_ENDPOINT/health before regenerating anything. Regenerating keys
during an outage creates work and fixes nothing.401 from one service only
401 from one service only
Almost always the key value itself. Check for a trailing newline — a key read
from a file written by a shell heredoc, or a Kubernetes Secret created with
--from-file, carries the newline as part of the value. --from-literal
does not add one.Then confirm the key has not been revoked: it disappears from the key list
entirely when it has.I revoked a key and traffic kept flowing
I revoked a key and traffic kept flowing
Only for about a second. Revoking drops the cached validation across every
receiver at once, so what remains is a request already in flight and a very
short per-process cache — not a multi-minute window.Traffic still arriving a minute later is a different key. Check the
key’s last-used timestamp in the list, and remember a key is
organization-wide: several services may share the one you did not revoke.
My script works, then stops after half an hour
My script works, then stops after half an hour
A session expires after 30 minutes and only auto-refreshes in a browser. A
long-running script must re-authenticate, or refresh before the deadline.
Next
Create a license key
Mint one, and the four things it does not control.
Quickstart
Use it to send your first telemetry.