Get started

Subjects

Your users never talk to us directly. You name each one with Docgen-Subject, and a session only opens for the key's organisation and that subject.

What a subject is

A subject is your own reference for an end user: a user ID, or a hash of one. Never an email or a name; we don't need to know who it is. We store it with the session and echo it back in session.subject.

Sending it

Send Docgen-Subject on every session call. It is required to start and list sessions; without it you get 422 subject_required.

cURL

curl https://api.129.212.147.181.sslip.io/v1/sessions \  -H "Authorization: Bearer $DOCGEN_API_KEY" \  -H "Docgen-Subject: wp_user:48213"

A session is bound to the subject it was created with. Every call on it, including POST /v1/documents with session, must send the same value. Any other value gets 404 session_not_found, exactly as if the session didn't exist. GET /v1/sessions returns only that subject's sessions; there is no call that lists across subjects.

Set it from your login

An ID is never a permission. Take the subject from your own authenticated session, never from what the browser sent: not a form field, not a query parameter, not a header your page sets.

Session IDs end up in URLs and logs. If your server forwarded whatever subject the browser claimed, anyone with a session ID could read another user's conversation. Taking it from your login means the session ID alone opens nothing.

Node.js

// Your server, behind your own login.app.post("/api/chat", requireLogin, async (req, res) => {  const r = await fetch(`${DOCGEN}/v1/sessions/${req.body.session}/messages`, {    method: "POST",    headers: {      Authorization: `Bearer ${process.env.DOCGEN_API_KEY}`,      "Docgen-Subject": `user:${req.user.id}`, // from your session, never from the request body      "Content-Type": "application/json",    },    body: JSON.stringify({ text: req.body.text }),  });  res.status(r.status).json(await r.json());});

Server only

Secret keys are refused from browsers. A request with an Origin header gets 401 secret_key_in_browser, so a key that leaks into a page can't be used from one. Your page calls your server; your server adds the key and the subject and calls us. The same goes for streams.

Turning subjects off

If your product has no end-user accounts (an internal tool, a single back-office user), your organisation can turn subjects off. Sessions then belong to the organisation alone, so any holder of the key and a session ID can open it.

← Authentication Test vs live →