← Back to blog

Analytics API Tokens Are Credentials, Not Identifiers

An API token grants access to data, so design it as a secret with a lifecycle: show it once, store a verifier, limit its authority, and make revocation routine.

An API token is not a label for a user or site. It is a credential: anyone who obtains a usable token may be able to act as its owner. Treating it like an identifier leads to tokens in logs, URLs, support screenshots, and long-lived configuration that nobody can revoke confidently.

The IETF's January 2025 OAuth 2.0 Security Best Current Practice updates the threat model and security guidance for OAuth deployments. While a personal API token is not necessarily an OAuth access token, the same core engineering principle applies: possession-based credentials must be protected in transit, restricted to the intended service, and limited to the authority the caller needs.

Reveal the secret once

Generate tokens with a cryptographically secure random source and enough entropy to prevent practical guessing. Return the complete token only at creation time, then store a non-secret prefix for identification and a one-way verifier for later lookup. If the database is copied, a verifier is safer than a reusable plaintext credential. Do not treat a general-purpose hash as a password hash: API tokens should have high randomness, while human passwords need a deliberately slow password-hashing function.

Make the one-time display explicit in the product UI and API response. After the user leaves the creation screen, provide a revoke-and-reissue path rather than a way to retrieve the original secret. Never put tokens in query parameters, page URLs, analytics events, error reports, or screenshots. URLs are copied into browser history, referrers, proxy logs, and support tickets more readily than authorization headers.

Send credentials in the right place

For HTTP APIs, accept tokens through the Authorization header over TLS. RFC 6750 describes bearer tokens as usable by any party that possesses them and warns that disclosure in storage or transport enables misuse. It also discourages putting bearer credentials in URI query parameters because URLs are likely to be logged. Reject tokens in query strings and request bodies unless a protocol specifically requires another transport and has a documented threat model.

On the server, validate the token before processing the requested operation. Resolve its owner and permissions from trusted storage; do not accept a user or site owner from the request as authority. Keep secrets out of application logs, traces, and exception messages. Log a token's non-secret ID or prefix when operational correlation is necessary, never the credential itself.

Scope, expire, and revoke

A token should grant the smallest useful set of permissions. Where the product supports it, let users limit a token to selected sites and read-only or specific operations. Do not silently give an automation script account-wide write access because it needs to fetch one report. The OAuth security best current practice discusses restricting token privileges and audiences; that is a useful design reference even when an API uses its own opaque token format.

Provide expiration and revocation as first-class controls. Shorter lifetimes reduce the period in which a leaked credential remains useful, while revocation handles incidents and staff or integration changes. If rotation requires overlap, define a bounded overlap window and show which token is active. Revocation must take effect at the API boundary, not only hide the token from the dashboard.

For Monoid's programmatic API, user-minted mnd_live_… tokens are opaque, returned in plaintext once, and stored as SHA-256 hashes with optional expiry and soft revocation. That storage design protects the original value from a database read, but it does not make a leaked live token harmless. Keep the token out of source control, CI output, browser bundles, and shared terminal history; issue a replacement and revoke the old one when exposure is suspected.

Make the lifecycle testable

Test the full sequence: create, use with the intended permissions, reject an invalid or expired token, revoke, then confirm the same token no longer works. Verify that a token cannot cross accounts or sites and that every endpoint applies the same authentication and authorization rules. Include operational checks that ensure logs redact credentials and API responses never return stored token material.

The secret-management lifecycle includes creation, access control, rotation, auditing, and revocation—not merely secure storage. An API token remains safe only when the system can identify its owner, limit what it can do, detect exposure without recording the secret, and shut it off promptly.

Sources

Comments

Loading comments…