Skip to content
Documentation Prelude Collector 1.0.0

Authentication

How to obtain and use API tokens for the Prelude Collector REST API, plus the unauthenticated endpoints you can rely on for liveness checks.

Every endpoint of the Prelude Collector REST API is gated by a bearer token, with two narrow exceptions reserved for tooling and liveness probes. After this first mention, the rest of this page refers to Prelude Collector as "the collector". This guide covers where tokens come from, how to attach them to a request, and what to do when authentication fails. For the full set of per-resource pages and a ready-to-run client, see the API reference and the Bruno collection.

When to use this API

You'll work with authentication in three situations:

  • Bootstrapping a new integration. You need a token to make any authenticated call — fetch one before you script anything else.
  • Running scheduled jobs. Long-running consumers (CI runners, Grafana sources, custom dashboards) should hold a token in a secret store, not regenerate it per call.
  • Wiring a liveness probe. The GET /api/v1/ping endpoint is unauthenticated by design. Use it from health checks where you cannot — or do not want to — distribute a token.

Common pitfalls

  • Forgetting the Bearer prefix. The Authorization header must read Bearer <your-api-token>. A bare token returns 401 Unauthorized.
  • Treating the token as a password. Tokens are JWTs. They encode an identity and an expiry; rotate them like credentials and do not commit them to source control.
  • Sharing one token across humans. If two people share a token and one leaves, you have to rotate for everyone. Issue one per consumer (per script, per service, per developer).
  • Using ping as an auth check. ping succeeds without a token, so it tells you nothing about whether your token works. To validate a token, hit any authenticated endpoint such as GET /api/v1/devices.

Worked example

The flow below obtains a token, exports it for the rest of the shell session, and verifies it works against an authenticated endpoint.

# 1. Obtain a token (see the Configuration guide for the exact
#    command shipped with your install).
export TOKEN="<your-api-token>"

# 2. Probe liveness without auth.
curl https://collector.example.com/api/v1/ping
# {"status":"ok","timestamp":"..."}

# 3. Validate the token by listing devices.
curl -H "Authorization: Bearer $TOKEN" \
  https://collector.example.com/api/v1/devices

Bruno: 01 Auth and Health / Ping (no auth), 02 Devices / List devices

A 200 OK from the third call means the token is valid and the collector accepted it. A 401 Unauthorized means the header is missing, malformed, or the token has expired — regenerate it and retry.

Reference

The full request and response schemas, including the unauthenticated ping endpoint, are documented in the Bruno collection. Use it to inspect headers and copy ready-to-run curl snippets.

See also

Filtering by: