# Manual management scripts

Out-of-band Auth0 ops that don't fit the regular `pnpm run deploy` flow. Each action is a thin wrapper around the Auth0 Management API (or the universal-login prebuild pipeline) and runs against a single tenant: `dev`, `qa`, or `prod`.

These scripts are intentionally not exposed as a top-level `pnpm` script, since most of them are dev / maintenance tools and a typo can hit prod. Run them via `ts-node` directly:

```
pnpm exec ts-node scripts/index.ts manual-management <action> <env> [args...]
```

## Prerequisites

`awsume` into the target account, that's it. The entrypoint hydrates `process.env` the same way the deploy does:

1. `config/<env>.env` is sourced (provides `CLIENT_ID` and other public ids).
2. AWS Secrets Manager fills the rest (path `<env>/auth0-hosted-pages/<NAME>`, names listed in `config/secret_names.txt`, including `CLIENT_SECRET`).
3. `AUTH0_DOMAIN` is read from `config/import.<env>.json` (canonical tenant, e.g. `workstation.auth0.com` for prod).

So a typical support run looks like:

```
awsume prod
pnpm exec ts-node scripts/index.ts manual-management generate-password-reset-link prod <email>
```

Existing `process.env` values from steps 1 and 2 are not overridden, so you can still pin a specific `CLIENT_ID` / `CLIENT_SECRET` via your shell when debugging. `AUTH0_DOMAIN` (step 3) is the exception: it's force-set from `config/import.<env>.json` so the entrypoint always targets the tenant matching the `<env>` argument, regardless of any pre-existing shell value.

## Support handoff: `generate-password-reset-link`

This is the one action in here aimed at non-engineers. If a user reports they didn't get the password reset email (spam, bounced domain, mailbox rejecting Auth0's sender, etc.), this mints a fresh reset URL you can paste into Zendesk, Slack, WhatsApp, or whatever channel actually reaches them. Auth0 doesn't store past reset URLs, so there's nothing to fetch after the fact, the script always mints a new one.

```
pnpm exec ts-node scripts/index.ts manual-management generate-password-reset-link <env> <email> [ttlSec]
```

Examples:

```
pnpm exec ts-node scripts/index.ts manual-management generate-password-reset-link prod jane.doe@example.com
pnpm exec ts-node scripts/index.ts manual-management generate-password-reset-link prod jane.doe@example.com 86400
```

Things to know:

-   Each call invalidates any previously-issued ticket for the same user. If support already sent one, this one wins.
-   `ttlSec` is optional, defaults to Auth0's default (5 days). Pass a positive integer in seconds if you need a tighter window.
-   If the email matches multiple identities the script errors out and lists the `user_id`s. Pick one manually and re-run after picking the right account in the Auth0 dashboard.
-   The post-reset redirect (where the user lands after submitting the new password) is computed by the universal-login page based on `appName` + `orgName`, so there's no `result_url` to pass in here.
-   The ticket is minted under the `settings-login` client (default user-management surface) so post-change-password Actions fire with the same context they would for a normal email-flow reset. No flag to override this in the script, edit it inline if you need a different client.

## Dev / maintenance actions

The rest of the actions are dev-flavored. They generally assume you know which template / prompt / org you're touching and how the prebuild pipeline transforms things.

> Heads up: these still go through the legacy `getAuth0Token` helper which reads `AUTH0_MACHINE_CLIENT_ID` / `AUTH0_MACHINE_CLIENT_SECRET`. Those names are NOT in `config/secret_names.txt`, so the awsume-only flow described above won't populate them. Export both manually in your shell before running any of the actions below, otherwise you'll hit a `getAuth0Token: Missing Auth0 credentials` error. Migrating these callers to `getManagementClient` is a future cleanup.

### `download-html-template <env> [tplName=universal-login]`

GETs the universal-login Liquid template currently live on the tenant and writes it to `src/branding/templates/<name>.<env>.html`. Useful for diffing what's deployed against what's on the branch.

### `upload-html-template <env> [tplName=universal-login]`

Reverse of the above: runs the local template through the prebuild pipeline (i18n + domain utils inject + tenant config + minify) and PUTs it to Auth0. Normally `pnpm run deploy` already does this, only reach for this when you need a one-off out-of-band push.

### `upload-email-template <env> [tplName=user_invitation]`

Same shape for email templates: loads the Liquid template, applies translations + tenant config + tenant env, and PUTs to `/api/v2/email-templates/<tplName>`. Same out-of-band caveat.

### `get-email-invitation <env> <organizationId> <invitationId>`

Read-only. Fetches the invitation URL for an existing org invitation. You'll need the org id and invitation id from the Auth0 dashboard or from logs first, so this is more of a debugging tool than a support tool.

### `download-prompts <env> [language=en] [filterPrompts]`

Pulls Auth0 prompt-screen i18n strings (login, signup, reset-password, mfa-\*, etc.) into `src/prompts/<lang>/`. Pass `filterPrompts` to limit which screen groups get downloaded.

## Adding a new action

1. Drop a folder under `scripts/manual-management/` with an `index.ts` that exports the function.
2. Wire the function into the `switch` in `scripts/manual-management/index.ts`.
3. If it's support-facing rather than dev-facing, give it its own section above instead of a one-line description in the dev list.