🚀 API Maker v2 to v3 repository migration prompt

⭐ Jun 2026 ⭐

Project Directory : /Volumes/Data/code/Git/sava_ecom_be Below is secret value and you can use that as auth provider name :

authTokenInfo_SAVA_ECom: <T.IAuthTokenInfo[]>[{
    "authTokenType": "AM_DB",
    "authTokenAMDB": {
        "instance": "mongodb",
        "database": "sava_ecom",
        "collection": "users",
        "usernameColumn": "username",
        "passwordColumn": "password",
        "expiresInSeconds": 259200
    }
}]

API Maker is a framework and it has it's own standard way of organizing backend code.
In project directory which uses API Maker v2 and we want to migrate that repository to API Maker V3.
Do NOT change any business logic or code other than what is described below.
Once you assign a name to a newly-created auth provider, use that exact same name everywhere it is referenced (in every authProviders array) so the references stay consistent.
You need to make below changes.

🔧 Manual task (do this first, yourself)

This step is manual — do it yourself before handing the rest of this prompt to an AI agent.

Deploy the repository to API Maker v3 first. The types.ts in a v2 repo is the old v2 file — it does not yet contain the v3 auth-provider interfaces or the authProviders field.
After deploying to v3, commit only the regenerated src/assets/schema-types/types.ts (the type interfaces referenced below live in that file).
Do this before any of the migration steps below, otherwise the new code will not reference the right symbols or typecheck.

🤖 Automated migration steps (for the AI agent)

0. Discover every occurrence first

Before editing anything, grep the entire repository for all v2 auth-field forms and enumerate every occurrence: authTokenInfo, IAuthTokenInfo, EAuthTokenType.
The settings categories in step 1 are a guide, not an exhaustive file list — migrate every occurrence you find.
Note that third party API settings exist at TWO levels — version-level (T.ITPApiSettingsTypes) and per-API level (T.ITPApiSettingsTypesAPILevel) — and both carry the auth field, so both must be migrated.
The type interfaces referenced below live in src/assets/schema-types/types.ts.

1. `authTokenInfo` → `authProviders`

authTokenInfo is now authProviders and it takes an array of strings (the names of the auth providers to use).
Make this change in instance, database, collection, API settings files, system API settings, third party API settings (both version-level and per-API level), custom API settings, and in secrets (the default secret also holds authProviders).
In v2 the auth config was written inline as an array of objects (there was no auth master). In v3 those objects move out into named auth providers (step 2) and the settings file only keeps the list of names.

In v2 the field looked like this (array of objects):

authTokenInfo: <T.IAuthTokenInfo[]>[
    {
        authTokenType: T.EAuthTokenType.AM_DB,
        authTokenAMDB: { instance: "...", database: "...", collection: "...", usernameColumn: "...", passwordColumn: "..." }
    }
]

In v3 it becomes just the list of provider names. Change the cast from <T.IAuthTokenInfo[]> to <string[]>, and remove any now-unused imports of T.IAuthTokenInfo / T.EAuthTokenType so the code still compiles:
```
authProviders: <string[]>["my_db_login", "my_google_login"]
```
An empty array (authProviders: <string[]>[]) keeps its v2 meaning: it overrides the default secret so only API Maker's API user token is accepted in x-am-authorization. Create no providers for an empty array.
If authTokenInfo is omitted, omit authProviders too (make zero edits to that file) — it will inherit from the default secret.
Leave apiAccessType exactly where it is. In v2 apiAccessType (NO_ACCESS | IS_PUBLIC | TOKEN_ACCESS) is a sibling api-level field next to authTokenInfo, not part of any token object — it is unrelated to the authProviders rename and must not be touched.

Idempotency / guardrails: If a settings file already uses authProviders (the v2 authTokenInfo key is not present), leave it untouched and create no duplicate providers. If a file contains neither key, make no edits to it. Always preserve existing formatting, comments, key order, and all unrelated fields. Re-running this prompt must be a no-op.

2. Create the Auth Providers from each object

In v2 there was no auth master — the auth config was defined inline as the array of objects inside each settings file, and those objects had no name.
In v3 auth is a master: every object must be extracted into one separate auth provider (a named master record) inside the new Auth Providers folder, and settings reference it by name.
De-duplicate across files: if the same inline auth object (same type and same data values) appears in more than one settings file, create only ONE shared provider and reference it by the same name from every file that used it. Two objects that differ in any value are distinct and each gets its own provider.
Since v2 objects have no name, assign each provider a unique, descriptive name derived from its purpose (e.g. customers_token, google_login). Use that exact name, referenced verbatim, in every authProviders array of step 1. If two distinct providers would end up with the same name, append a numeric suffix (_2, _3). Only @ and / are stripped from a provider name when it is written to disk, so avoid those two characters in names.
Map the v2 authTokenType and its data object to the v3 provider type as follows:

v2 `authTokenType`	v2 data object	v3 provider type	property reference in `types.ts`
`AM`	`authTokenAM` (`{ u, p }` or `{ refresh_token }`)	no provider — this is the API Maker user token; referenced by sending `x-am-authorization`. Do not create a provider for it.	`IAuthTokenAM` / `IRefreshTokenAM`
`AM_DB`	`authTokenAMDB`	`DB_TOKEN_GENERATOR`	`IAuthTokenAMDB`
`GOOGLE`	`authTokenGoogle`	`GOOGLE`	`IAuthTokenGoogle`
`AWS`	`authTokenAWS`	`AWS`	`IAuthTokenAWS`
`AZURE`	`authTokenAzureAD`	`AZURE`	`IAuthTokenAzureAD`

v2 EAuthTokenType has exactly these five members: AM, AM_DB, GOOGLE, AWS, AZURE. There is no CUSTOM member and no authTokenCustom object in v2 — do not look for them. CUSTOM_TOKEN_GENERATOR is a v3-only provider type with no v2 source to migrate.

You can check the property details in the types.ts file for IAuthTokenAMDB, IAuthTokenGoogle, IAuthTokenAWS, IAuthTokenAzureAD.
Per-type fields to carry over (verify against src/assets/schema-types/types.ts and src/ajv/mongoose/MongooseAuthProviders_Vali.ts):
- AM_DB → DB_TOKEN_GENERATOR: carry instance, database, collection (MongoDB) or table (SQL), usernameColumn, passwordColumn, and also the two load-bearing columns passwordChangedAtColumn and groupsColumn. groupsColumn drives group/role access; passwordChangedAtColumn changes the JWT contents (when set, the password field is not stored in the JWT — this timestamp is stored instead so password changes can be detected).
- AWS: cognitoUserPoolId, region, tokenUse ('access' | 'id'), tokenExpiration (in milliseconds).
- AZURE: the field is appId (documented as the OAuth client_id), NOT clientId. Carry appId, tenant, audience, issuer, maxRetries.
- GOOGLE: clientId.
Groups / roles config (AWS, Azure, Google only): these three providers each also carry the shared IAuthTokenGroupsProperties config — sourceFieldOfUniqueId (the token field holding the user's unique id) and groupsDataSource ({ instance, database, collection? / table?, targetFieldForUniqueId, groupsColumn, select? }). Carry these over for any AWS/Azure/Google object that defines them, or group/role access for federated tokens will be lost. (For AM_DB the equivalent is the inline groupsColumn field — there is no groupsDataSource.)
expiresInSeconds is v3-only. v2 has no per-token expiresInSeconds (the AM token lifetime was global, default 3600s). Do not try to migrate it from v2 — set it fresh in v3 if desired, respecting the v3 minimum of 600.
Inside the Auth Providers folder, each provider named <name> uses these files:
- <name>.yaml — the config file that stores generatorType (DB_TOKEN_GENERATOR / CUSTOM_TOKEN_GENERATOR / AWS / GOOGLE / AZURE) and the materialized config fields. This is the source of truth for the provider type, and generatorType is required. AWS, Azure, Google and DB providers all present on disk as just <name>.ts (plus a possibly-empty <name>.fg.ts) and are indistinguishable by file presence — so you must write the correct generatorType into <name>.yaml; never try to reconstruct the type from which .ts/.tg.ts/.tv.ts/.fg.ts files exist.
- <name>.ts — basic info / DB token generator code.
- <name>.tg.ts — custom token generator code (only for CUSTOM_TOKEN_GENERATOR).
- <name>.tv.ts — custom token validator code (only for CUSTOM_TOKEN_GENERATOR).
- <name>.fg.ts — fields generator code. This is a NEW, optional v3 concept — v2 had no fields generator (which DB columns became token claims was implicit in the AM_DB column config). Generate it only if you want to inject specific fields into the token; there is no v2 source to copy from. (On write, .fg.ts is always emitted for DB_TOKEN_GENERATOR even when empty, and only when a fields-generator function is set for CUSTOM_TOKEN_GENERATOR.)

3. Get Token

The Get Token API and the call from code is now changed. It just needs the provider name and all other information will be picked up automatically from the auth providers master. Please check the example below.
The request body accepts: name? (optional), u, p, refresh_token? (optional — re-issues a token without u/p), and expiresInSeconds? (optional). Routing is by name:
- When name is omitted, the request hits the API Maker user path, where the request body's expiresInSeconds is honored directly.
- When a name is supplied, it resolves a DB/Custom auth provider and the token expiry comes from that provider's configured expiresInSeconds (the request-body value is ignored on that path).
```
[
    {
        "name": "token_generator_name",
        "u": "[email protected]",
        "p": "student1"
    },
    {
        // When name is not provided, system will generate API Maker User's token
        "u": "default",
        "p": "12345",
        "expiresInSeconds": 259200
    }
]
```
Get Token only mints tokens for DB_TOKEN_GENERATOR and CUSTOM_TOKEN_GENERATOR providers. For AWS (Cognito), Google, and Azure providers, API Maker does NOT issue tokens — the client obtains its own provider-issued token from the external identity provider and sends it to API Maker, which only validates it. There is no Get Token login flow for AWS/Google/Azure.
Each provider type's token goes in its own request header — update client call sites accordingly:

Provider	Request header
API Maker user/admin token (name-less Get Token result)	`x-am-authorization`
`DB_TOKEN_GENERATOR`	`x-am-user-authorization`
`CUSTOM_TOKEN_GENERATOR`	`x-custom-authorization`
`AWS`	`x-aws-authorization`
`GOOGLE`	`x-google-authorization`
`AZURE`	`x-azure-authorization`

WebSocket note: the WebSocket connection querystring key is still literally authTokenInfo in v3 (it carries the provider names) — do not rename it to authProviders in WS query strings, or connections will fail token validation.

4. After migration — verify

Make sure every name listed in any authProviders array has a matching auth provider in the Auth Providers folder.
Confirm the number of distinct auth providers you created equals the number of distinct auth objects in the original v2 authTokenInfo arrays.
Make sure no authTokenInfo field (or IAuthTokenInfo / EAuthTokenType references / imports) remains anywhere in the migrated repository — except the WebSocket querystring key noted in step 3.
If the target repo is a buildable TypeScript project, run its build/lint and confirm it compiles after the cast and import changes.

🚀 API Maker v2 to v3 repository migration prompt

⭐ Jun 2026 ⭐

🔧 Manual task (do this first, yourself)

🤖 Automated migration steps (for the AI agent)

0. Discover every occurrence first

1. authTokenInfo → authProviders

2. Create the Auth Providers from each object

3. Get Token

4. After migration — verify

1. `authTokenInfo` → `authProviders`