Docs

Authentication

Create API keys, understand read and write grants, and control browser origins.

The Public API authenticates every request with a static API key sent as a bearer token:

curl https://actions.einblick.xyz/api/v1/events \
  -H "Authorization: Bearer api_YOUR_KEY"

Requests without a valid key receive 401 Unauthorized.

Creating API keys

API keys are managed in the Einblick app under System settings → Integrations → Public API. When you create a key you give it a name, optional expiry, and a set of grants. The token (api_ followed by 48 hex characters) is shown once at creation time — store it in your secret manager; Einblick only keeps a hash.

Keys can be revoked at any time. Expired and revoked keys are rejected with 401 Unauthorized.

Read grants and write grants

Grants are configured per key and are strictly separated:

  • Read grants control which resources and which of their fields the key can fetch. A read grant can also carry backend-enforced filters — for example an events grant limited to status = published. Filtered-out records are simply absent from responses; there is no way to opt out from the client.
  • Write grants are per resource, per action (create, update, delete), and per writable field. Read grants never imply write grants.

The key-scoped schema at GET /api/v1/schema reflects exactly what the key can do: readable fields, writable fields, and supported write actions per resource.

Browser usage and allowed origins

By default the API responds with Access-Control-Allow-Origin: *, which assumes the key is used from trusted server-side code.

If you must call the API from a browser, configure an origin allowlist on the key. Cross-origin requests are then only accepted from those exact origins (for example https://www.example.com); anything else receives 403 with the code origin_not_allowed.

Treat API keys like passwords. Prefer server-side usage. Only use a key in the browser when it is restricted to specific origins and read-only, narrowly-scoped grants.

Key hygiene

  • Create one key per integration so you can revoke them independently.
  • Set an expiry for keys used in short-lived integrations.
  • Scope grants to the minimum resources, fields, and actions needed.
  • Rotate keys by creating a replacement, deploying it, then revoking the old key. The app shows a "last used" timestamp per key to verify the old key has gone quiet.