====== Users, roles, and JWTs ======

Each user has a local role and a generated HMAC signing secret. The supplied roles are examples and must be reviewed against your own access requirements.

^ Role ^ Intended starting point ^
| ''readonly'' | Read-only API operations |
| ''support'' | Read-only access plus selected support operations |
| ''senior-support'' | Broader operational access |
| ''billing'' | Account, invoice, balance, and usage access |
| ''admin'' | Every action explicitly mapped by the gateway policy |

Even the ''admin'' role is fail-closed: an unknown or newly added API operation is denied until the policy is updated. Exact mappings are in [[https://github.com/01ax/binarylane-scoped-api-proxy/blob/main/manifest/roles.json|manifest/roles.json]].

===== Add or rotate a user =====

<code bash>
sudo /opt/bl-proxy/scripts/add-user.sh alice readonly
</code>

Running the command again for an existing username rotates that user's signing secret and invalidates JWTs signed with the previous secret. User details are stored under ''/opt/bl-proxy/secrets/'' with root-only permissions.

===== Generate a JWT =====

<code bash>
TOKEN=$(sudo /opt/bl-proxy/scripts/make-jwt.sh alice '<user-secret>')
curl -H "Authorization: Bearer $TOKEN" https://proxy.example.com/v2/servers
</code>

Give each user only their own secret. Do not place the master API token, signing secrets, or JWTs in URLs, source control, cloud-init, screenshots, or support tickets.

===== Change a role =====

Edit ''/opt/bl-proxy/manifest/users.json'', then redeploy the scoped policy:

<code bash>
sudo /opt/bl-proxy/scripts/deploy-scoped.sh
</code>

Test role changes against non-production or disposable resources before relying on them.