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:

Environment variable HEREMYAPP_TOKEN
File ~/.config/heremyapp/token
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.

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"

{"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:

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):

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.