<!-- https://predictabl.tech/docs/authentication/ -->
# Authentication

Every request carries an API key (a *token*). A token belongs to one account
and reaches only that account's data and models.

## Create a token

In the web app, open **Settings → API & MCP**, give the token a name
(for example *Nightly churn script*) and select **Create token**. The token starts with `pk_` and is **shown only once**: Predictabl
stores only a hash of it, so it cannot be shown again. If you lose it, create
another and revoke the old one.

## Full access or predictions only

A new token has **full access**: from code, it can do what you do in the web
app (upload data, ask questions, plan, train and get predictions), on your own
account only.

Tick **Predictions only** for a read-only token: it can get predictions and
model results from your trained models, and change nothing. Use it for someone,
or an app, that should only use your predictions.

| | Full access | Predictions only |
|---|---|---|
| Get predictions and model results | ✓ | ✓ |
| Upload data, ask, plan, train | ✓ | |
| Change your AI-provider setting | ✓ | |
| Create or revoke tokens | | |

A token can never reach another account's data or models: someone else's model
looks exactly like one that does not exist (`404`).

## Use the token

```bash
export PREDICTABL_API_KEY=pk_...
```

```python
import predictabl as pb

print(pb.account())   # who the token belongs to, plan, what is left
```

Or pass it explicitly, for example to use two accounts in one script:

```python
client = pb.Client(api_key="pk_...")
client.account()
```

Over REST, send it as a bearer token:

```bash
curl https://app.predictabl.tech/pub/v1/account \
  -H "Authorization: Bearer $PREDICTABL_API_KEY"
```

## Which server

| | Base URL |
|---|---|
| Hosted app (default) | `https://app.predictabl.tech/pub/v1` |
| Your own instance | `http://localhost:8000/api/v1` |

```bash
export PREDICTABL_BASE_URL=http://localhost:8000/api/v1
```

or `pb.Client(base_url="http://localhost:8000/api/v1")`.

## Revoke a token

**Settings → API & MCP → Your tokens**, then the bin icon. It stops
working on the next request; there is no cache to wait for.

## Keep it safe

- Read the key from the environment or a secrets manager. Never commit it.
- One token per script or service, named after it, so you can revoke one
  without breaking the others.
- Tick **Predictions only** wherever building is not needed.
- If a token leaks, revoke it. **Settings → API & MCP** shows when each
  token was last used.
