# Authentication

Every API call needs `Authorization: Bearer <token>`. Tokens start with `hma_`.
There is no self-signup yet: the account owner creates tokens and gives them to people or agents.

## Where the token comes from

Agents resolve the token in this order:

1. Environment variable `HEREMYAPP_TOKEN`
2. File `~/.config/heremyapp/token`
3. Otherwise, ask the user for a token. Do not try to create an account.

Never print, log or commit the token, and never put it in site files.

```bash
export HEREMYAPP_TOKEN="${HEREMYAPP_TOKEN:-$(cat ~/.config/heremyapp/token 2>/dev/null)}"
API=https://api.heremyapp.com/v1
AUTH="Authorization: Bearer $HEREMYAPP_TOKEN"
curl -sS --fail-with-body "$API/me" -H "$AUTH"
```

```json
{"account":{"id":"acc_9x2k...","username":"peter"},"token":{"id":"tok_4m8q...","scope":"account"}}
```

`account.username` is the `ACCOUNT` part of every URL.

To store a token for agents on this computer:

```bash
mkdir -p ~/.config/heremyapp && chmod 700 ~/.config/heremyapp
pbpaste > ~/.config/heremyapp/token && chmod 600 ~/.config/heremyapp/token   # macOS, token copied to clipboard
```

## Scopes

| Scope | Can do |
|---|---|
| `account` | Create spaces, deploy and roll back any space, upload installers, create and revoke tokens |
| `space` | For one space only: view it, deploy and roll back, upload and delete installers |

A space token gets `403 forbidden` for any other space, and for creating spaces or managing tokens.
If `/me` reports `"scope":"space"`, run `GET $API/spaces`: it returns the one space the token is for.
If the user wants a different space, ask them for an account token.

## Creating and revoking tokens

With an account token, create a token limited to one space (for CI or a single project's agent):

```bash
curl -sS --fail-with-body -X POST "$API/tokens" -H "$AUTH" -H "content-type: application/json" \
  -d '{"name":"my-app agent","space":"my-app"}'
```

The response contains `token` once; it cannot be shown again. List tokens with `GET $API/tokens` and revoke one with
`DELETE $API/tokens/TOKEN_ID`. Revoked tokens stop working immediately.