HOWTO: Set up as a developer to use `wbsp`

When you need this

Do this once per machine so you can run wbsp against a WBSP platform — to deploy your app, manage demos, etc. — signing in as yourself, without AWS credentials. After it, wbsp remembers who you are and talks to the platform API on your behalf.

You do not need this if you're a platform operator driving raw AWS deploys with --backdoor (that path uses your AWS creds directly and skips login) — but every normal developer workflow goes through login.

What this actually does (plain English)

wbsp can reach the platform two ways:

Via the API (default, and what this guide sets up). You sign in once with wbsp login; every command then sends your cached token to the platform API (api.wbsp.ai). No AWS credentials required.
Direct (--backdoor). Build/push/deploy straight to AWS using your own AWS credentials. Operator-only; ignore it as a developer.

wbsp login is an ordinary browser OIDC sign-in against HAP (the platform's auth server). It opens your browser, you sign in, and the resulting token is cached on disk; subsequent commands reuse it until it expires.

One thing to understand up front: being signed in is not the same as being allowed. Your token identifies who you are; you also need the deployer role in the tenant (the isolation boundary your apps live in) before your commands are authorized.

That grant is made by the tenant's own administrator, in the identity provider's screens. No platform operator is involved. If you are the tenant's administrator, you grant it to yourself. A refusal names the tenant, the permission you lack and where to get it, so you are never left guessing which of the two you are missing.

Prerequisites

A HAP account (your normal wbsp.ai website account works — the CLI signs in against the website's shared HAP by default)
The wbsp binary — make build in the platform repo, or install it

No environment variables are needed against the wbsp.ai platform: the CLI defaults to https://api.wbsp.ai for the API, the website's shared HAP as the login issuer, and the registered CLI client id. Only for a self-hosted / dev platform, ask your operator for override values:

WBSP_API_URL — the wbsp-api endpoint (default https://api.wbsp.ai)
WBSP_HAP_ISSUER — e.g. https://hap.wbsp.ai/t/<tenant>
WBSP_CLI_CLIENT_ID — the CLI's OIDC client id (hap_…)

Steps

What: log in via your browser. Why: every later command sends the cached token to the API.

wbsp login                    # signs in to tenant `wbsp` — where website accounts live
wbsp login --tenant <name>    # …or to another tenant you hold an account in

A browser opens — sign in. On success you'll see signed in to tenant wbsp as <you> and token cached at ~/.config/wbsp/tokens/wbsp. (Self-hosted platforms only: put the three override exports from the prerequisites in your shell profile first.)

2. Get your `sub` and give it to your tenant's administrator

What: read your identity from the platform and send it to whoever administers the tenant you need to deploy to. That is the tenant's own administrator — not a platform operator, and not the wbsp.ai team. If the tenant is yours, this is you. Why: the grant is made against your sub, the identifier your sign-in carries (login tokens carry no email address, so email alone isn't enough to identify you).

curl -s -H "Authorization: Bearer $(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.config/wbsp/token")))["access_token"])')" \
  "${WBSP_API_URL:-https://api.wbsp.ai}/api/v1/me"
# → {"sub":"…","email":"","admin":false,"tenants":null,"source":"hap"}

Send your operator your email and that sub. On their side they create / update your user with that sub and grant you the tenant(s) you need (and admin, if applicable).

3. Confirm you're authorized

What: re-check your identity after the operator grants you. Why: until a tenant appears in tenants, commands targeting it return 403.

# same command as step 2 — now expect your tenant(s):
# → {"sub":"…","tenants":["<your-tenant>"], …}

4. Use `wbsp`

With a valid cached token, commands route through the API automatically — no AWS creds, no --backdoor (the API defaults to https://api.wbsp.ai; WBSP_API_URL overrides it):

# deploy your app (from your app directory, through the API):
wbsp deploy --destination <your-destination>

# demos (run in the app dir — variant + tenant come from wbsp.yaml + the `demo` destination):
wbsp demo status     # is a demo available? any running? time left?
wbsp demo launch     # launch one; prints its URL + expiry
wbsp demo remove --name <instance-id>              # reap one early

Your token expires periodically; when it does, just run wbsp login again.

Troubleshooting

Symptom	Cause / fix
You enter the login code and the browser returns to the login screen, no error	Your `wbsp` is out of date — a current build sends `consent=granted` automatically. Rebuild/update it.
`WBSP_API_URL is required for the default API path`	Your `wbsp` is out of date — current builds default to `https://api.wbsp.ai`. Rebuild/update it, or export `WBSP_API_URL`. (Only operators use `--backdoor` instead.)
`403` / "not permitted for this tenant"	The operator hasn't granted your `sub` that tenant yet (step 2).
`401` on a command that worked before	Cached token expired — run `wbsp login` again.
`login` can't open a browser (headless/SSH box)	Run login on a machine with a browser; the token cache (`~/.config/wbsp/token`) can be copied, or ask your operator for a CI service token and set `WBSP_API_TOKEN` instead.

HOWTO: Set up as a developer to use wbsp