Datalumo
Docs · Authentication ▾
View as Markdown →

Authentication

#API keys

Server-side calls (pushing pages, listing content, and optional widget access) use an API key for your organisation. Create keys on the API keys page in the dashboard.

Send the key on every request:

Authorization: Bearer YOUR_API_KEY

You can choose permissions for each key, and optionally limit it to specific sources.

#Permissions

Permission Allows
pages.read List pages for a source
pages.write Create, update, and delete pages
search Call search on a widget with this key
chat Call chat on a widget with this key
summarize Call summarize on a widget with this key

If a key is missing the permission for a request, the API returns 403.

#Source limits

When you create a key you can restrict it to one or more sources. A limited key:

  • only lists those sources from GET /me
  • is rejected with 403 if it targets any other source

Keys without a source limit can access every source in the organisation.

#Auth errors

Status Meaning
401 Missing, invalid, or expired API key
403 Key is for another organisation, lacks a permission, or is outside its source limit
404 Unknown organisation or source

#Widget authentication

Widget endpoints (/widgets/{widget}/…) accept any of the following:

  1. Your website domain. The request comes from a domain on the widget's website list. This is how the public embed works in the browser.
  2. Widget secret key. Authorization: Bearer … with the secret shown once when you create the widget. Use this from your server.
  3. Organisation API key. A key that has the matching permission (search, chat, or summarize) and can access every source that widget uses.

A search widget cannot handle chat requests, and a chat widget cannot handle search-only endpoints that require the other type.

#Signed visitor identity

To load conversation history or keep conversations for a logged-in visitor, prove the visitor id on your server. Sign it with the widget's signing secret:

$hash = hash_hmac('sha256', $userId, $signingSecret);

On chat, send:

{ "user": { "id": "user-42", "hash": "…" } }

On conversation routes, send user and hash as query parameters or in the body. If the hash is wrong, the request fails. Datalumo will not treat a failed proof as an anonymous visitor.