Skip to content
Documentation Prelude Topology Engine 1.0.0

Authentication

How to obtain and use API tokens for the Prelude TE REST API, plus the unauthenticated endpoint you can rely on for liveness probes.

Every endpoint of the Prelude TE REST API is gated by a Bearer token, with a single narrow exception reserved for liveness probes. After this first mention, the rest of this page refers to Prelude TE as "the engine". 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 call any authenticated endpoint — generate one before you script anything else.
  • Running scheduled jobs. Long-running consumers (CI runners, dashboards, custom subscribers) should hold a token in a secret store, not regenerate it per call.
  • Wiring a liveness probe. The GET /api/health 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 /api/health as an auth check. Health 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/bgp/peers.

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. Generate a token in the Prelude TE UI:
#    Settings → API Tokens → Create. Copy the token.
export TOKEN="<your-api-token>"

# 2. Probe liveness without auth.
curl https://te.example.com/api/health?verbose=false
# {"status":"ok","service":"prelude-te","uptime_seconds":...}

# 3. Validate the token by listing BGP peers.
curl -H "Authorization: Bearer $TOKEN" \
  https://te.example.com/api/bgp/peers

Bruno: Health / Get health, BGP Peers / List peers

A 200 OK from the third call means the token is valid and the engine 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 health endpoint, are documented in the Bruno collection. Use it to inspect headers and copy ready-to-run curl snippets.

See also

Filtering by: