Authenticating to the API

Every request to api.getfluxly.com/v1/* carries an API key. There are two kinds and they aren't interchangeable.

| Type | Prefix | Where it lives | What it can do | | --- | --- | --- | --- | | Publishable | gflux_pub_ | Browser code, public sites | Ingest events | | Server | gflux_secret_ | Backend services, never in client bundles | Ingest, identity alias, GDPR erase |

Each key is bound to exactly one project. You cannot move events across projects with a single key.

Bearer header (recommended)

POST /v1/events HTTP/1.1
Host: api.getfluxly.com
Authorization: Bearer gflux_pub_abcdef1234
Content-Type: application/json

Query parameter fallback

Some embedded environments cannot set headers. In those cases pass the key as ?api_key=.... Use it only when you have to; query strings show up in proxy logs.

POST /v1/events?api_key=gflux_pub_abcdef1234 HTTP/1.1

What happens with the wrong key

| HTTP | Body error | Meaning | | --- | --- | --- | | 401 | unauthenticated | No key or key not recognized | | 403 | wrong_key_type | Valid key, wrong classification (e.g. publishable key on a server-only endpoint) | | 403 | forbidden | Valid key, project doesn't have access to this resource |

wrong_key_type returns the received classification so the caller can adjust without trial and error:

{
  "error": "wrong_key_type",
  "detail": "This endpoint requires a server key. Server keys are for backend code; publishable keys are for browser code.",
  "received": "publishable"
}

Rotating keys

Generate the new key in the dashboard, deploy it everywhere, then delete the old one. The API does not return a revoked key's body in errors.