# Authentication

Unibot accounts live in the `users` collection. You can sign in with an emailed one-time code or with an email and password. Both give you the same kind of token.

## Sign-up and the one-time code

1. `POST /api/collections/users/records` with `email`, `password` and `passwordConfirm` creates the account. Sign-up is open to anyone.
2. `POST /api/collections/users/request-otp` with `{"email": "..."}` emails a six-digit code and returns an `otpId`. The code is valid for 10 minutes.
3. `POST /api/collections/users/auth-with-otp` with `{"otpId": "...", "password": "<code>"}` returns a token and marks the email as verified.
4. Confirming an email this way clears the password you registered with. Set it again with `POST /v1/account/password` and `{"password": "...", "passwordConfirm": "..."}`, sending the token you just received. The response holds a fresh token; the old one stops working.

If the email does not belong to an account the request still answers with an `otpId`, but no email is sent.

## Logging in with a password

```bash
curl -X POST https://theunibot.com/api/collections/users/auth-with-password \
  -H "content-type: application/json" \
  -d '{"identity":"you@example.com","password":"a-long-password"}'
```

Password login only works once the email is verified. Until then the call returns `403`.

## Using the token

Send the token in the `Authorization` header. Both forms work for the REST API:

```
Authorization: Bearer <token>
```

The MCP server accepts the same bearer token. See [MCP server](/docs/mcp).

Tokens last five days. Renew one with `POST /api/collections/users/auth-refresh` while it is still valid.

## Who can see what

| Resource | Who can list and read | Who can create | Who can change or delete |
| --- | --- | --- | --- |
| Your user record | you | anyone (sign-up) | you |
| Bots | the owner | any signed-in user, as owner | the owner |
| Answers | the owner of the bot | the owner of the bot | the owner of the bot |
| Public bot answers | anyone, only through `GET /v1/bots/{slug}/ask` | n/a | n/a |

A public bot is not readable through the collection endpoints by anyone but its owner. The public ask route is the only anonymous way in, and it returns just the matched answers.

## Password reset

`POST /api/collections/users/request-password-reset` with `{"email": "..."}` emails a link to a confirmation page where you choose a new password.

## Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid input, or a wrong code or password |
| 401 | The bearer token is missing, invalid or expired |
| 403 | The token is valid but you may not do this, or the email is not verified yet |
| 404 | The record does not exist or is not yours |
