Authentication

How to authenticate against the Hypeline API with scoped API keys, which headers to send, how scopes and per-key rate limits work, and how to rotate or revoke a key instantly.

Every request to the API is authenticated with an API key. Keys are scoped, rate-limited per key, hashed at rest, and revocable on their own, so you can issue one per integration and cut any single one off without touching the others.

Get a key

Keys are created in the dashboard, one place, shown once:

Sign in at app.hypeline.io.
Open API keys at app.hypeline.io/keys.
Click Create key, name it after the integration it is for, and choose its scopes.

A key is a hype_ prefix followed by 256 bits of randomness. The plaintext is displayed once, at creation, and never again: we store only a SHA-256 hash and a short display prefix, so we could not show it to you again even if you asked. Copy it immediately and keep it somewhere secret.

bash

export HYPELINE_KEY="hype_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Send the key

Present the key on every request in the Authorization header as a bearer token (preferred):

bash

curl -H "Authorization: Bearer $HYPELINE_KEY" https://api.hypeline.io/v1/sources

An X-API-Key header is also accepted, which is convenient for tools that reserve Authorization for something else:

bash

curl -H "X-API-Key: $HYPELINE_KEY" https://api.hypeline.io/v1/sources

Header only, no query-parameter key

The API reads the key from a header only. There is no ?api_key= query parameter, so a browser's bare EventSource (which cannot set headers) is rejected with 401. To stream from a browser, use fetch() with a streaming body reader. See the quickstart.

Scopes

A key carries only the scopes you grant it, and a request outside those scopes is rejected with 403. Grant each key the least it needs.

Scope	Grants
`stream:read`	Read the live event stream (`GET /v1/stream`) and any channel (`GET /v1/streams/{channel}`).
`sources:read`	List and inspect sources, their health, and detection results.
`sources:write`	Add, edit, disable, and delete sources.

A key scoped to a single channel (stream:read:{channel}) can read that channel and no other, so you can hand a downstream consumer exactly one slice of the stream.

Rate limits

Each key has its own rate limit, enforced by a token bucket that is independent from every other key, so one busy integration cannot starve another. When a key exceeds its limit the API returns 429 with a Retry-After header giving the whole number of seconds to wait:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/problem+json

Honor Retry-After and retry after the delay. The limit is a property of the key, so a workload that needs more headroom gets its own key rather than sharing one.

Rotate and revoke

Keys are cheap and independent, so rotation is just create-then-delete with no shared state to coordinate:

Create a new key in the dashboard and deploy it to the integration.
Confirm the integration is authenticating with the new key.
Delete the old key.

Deleting a key revokes it immediately: the very next request carrying it gets 401, and no other key is affected. There is no separate "disable" step and no grace window to reason about, so a leaked key is stopped the moment you delete it.

Two different rotations

This page is about rotating an API key (create a new one, delete the old). That is distinct from rotating a webhook signing secret, which is a zero-downtime overlap on a single destination. See rotating your signing secret.

Errors

Status	Meaning
`401`	The key is missing, malformed, or revoked.
`403`	The key is valid but lacks the scope the operation requires.
`429`	The key's rate limit is exceeded. Honor `Retry-After`.

Every error is an RFC 9457 application/problem+json document with type, title, status, and detail.