Authenticate writes · BINA Docs

Require a token for state-changing requests and bind attribution fields to the authenticated operator.

By default a local BINA process has no login: it binds 127.0.0.1 and relies on Host and Origin allowlists. Use this guide when more than one person writes to the same instance and you need attribution you can trust.

#1. Issue operator tokens

Set CLEARY_OPERATOR_TOKENS to a comma-separated list of operator:token pairs:

.env.local

CLEARY_OPERATOR_TOKENS=Ariel:replace-with-a-long-random-token,Mathéo:replace-with-another-token

Generate tokens with a secure source, for example openssl rand -hex 32. Once any token is set, every POST and DELETE must authenticate. To require authentication with no tokens configured (refusing all writes), set CLEARY_REQUIRE_AUTH=1.

#2. Send the token

Use either header:

bash

curl -s -X POST http://127.0.0.1:8787/v1/radar/watchlist \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alphabet","interest":"client"}'

X-Cleary-Token: <token> is accepted as an alternative to Authorization: Bearer.

#3. Understand attribution

When a request is authenticated, BINA fills the attribution fields (by, reviewedBy, counsel, requestedBy, importedBy, proposedBy, estimatedBy) from the token's operator. Claiming a different name is refused with 403.

#Responses

Status	Code	When
`401`	`operator_auth_required`	A write with no token, or a token that matches no operator.
`403`	—	The body names a different operator than the token.

#Shared review password

A deployed review workspace can also be gated with a shared password: set BINA_REVIEW_PASSWORD on the server and send it as the X-Bina-Password header. The console asks for it once per tab and keeps it in sessionStorage. This is a gate, not an identity — combine it with operator tokens when attribution matters.