Authentication

Status: pilot. Draft — needs review before publishing.

The API uses a per-user token. There is no shared API key.

Header

Authorization: Token <your-token>

The token is issued by POST /auth/register/ and POST /auth/token/.

Endpoints

Method	Path	Purpose
POST	/auth/register/	Create a user, an account and a welcome balance; returns a token
POST	/auth/token/	Exchange email and password for a token
POST	/auth/password-reset/	Request a reset link
POST	/auth/confirm/	Set a new password from the reset link
GET	/accounts/me/	Account name, credit balance, content rules

Registration

Fields: email, password, company_name. The password must be at least 8 characters. The response contains both the token and the account:

{ "token": "...", "account": { "id": "...", "name": "...", "credit_balance": "5.0000" } }

A new account receives a welcome balance. Enrichment draws from that balance; a request without enough credit fails with 402 insufficient_balance.

Login

username is the email address, not a separate login name.

Password reset

POST /auth/password-reset/ always answers 200 with the same neutral message, whether or not the address is registered. This is deliberate: the endpoint must not reveal which addresses exist. Do not treat a 200 as proof that a letter was sent.

If a reset link cannot be delivered, the same 200 is returned. POST /auth/confirm/ takes the uid and token from the link and sets a new password.

Sign-out

There is no logout endpoint. A token stays valid until it is rotated; a client signs out by discarding it.

Where the token lives

The token must not be readable by page scripts. Calls are made server-side, from the application's own server functions or proxy, which attaches the header. If an integration calls the API directly from a browser, it needs CORS to be enabled for its origin — it is not enabled by default.

Next

• Errors
• API reference