From c89929e86220b69f05ce194729454ba36ae1fd50 Mon Sep 17 00:00:00 2001 From: yardend Date: Wed, 14 Oct 2026 11:41:08 +0300 Subject: [PATCH 1/3] docs(ai-gateway): document the service-role-only gateway rule Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/sdk/src/modules/ai-gateway.types.ts | 21 +++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/packages/sdk/src/modules/ai-gateway.types.ts b/packages/sdk/src/modules/ai-gateway.types.ts index 7abd9ab9..319394c0 100644 --- a/packages/sdk/src/modules/ai-gateway.types.ts +++ b/packages/sdk/src/modules/ai-gateway.types.ts @@ -5,8 +5,10 @@ export interface AiGatewayConnection { /** Base URL of the selected gateway provider. */ baseURL: string; /** - * Bearer token that authenticates the request. Empty string when the caller is - * unauthenticated. + * Bearer token that authenticates the request: the service-role token from + * `base44.asServiceRole.aiGateway`, or the signed-in user's token from + * `base44.aiGateway`. The user token is an empty string when no one is signed + * in, and the gateway rejects that call. */ token: string; /** @@ -95,7 +97,20 @@ export interface AiGatewayModuleConfig { * The mode determines which token `connection()` returns: * * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. - * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. Use it from backend functions: apps that restrict Core integrations, the default for new apps, reject user-token gateway calls on public apps. It also works when there's no signed-in user, such as from a scheduled automation. + * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. + * + * Use service role from a backend function, as every example here does. The + * gateway accepts a user token only on apps shared privately or with your + * workspace. It rejects anonymous calls, and user-token calls on public apps, + * with a `403` and the error code `ai_gateway_requires_service_role`, so a + * visitor can't spend your app's credits by calling the gateway from the + * browser. A user-token call therefore works while you're building and starts + * failing the moment you share the app publicly. Service role also works when + * there's no signed-in user at all, such as from a scheduled automation. + * + * To control who triggers a billed request, check the caller with + * `base44.auth.me()` in your backend function before calling the gateway, and + * call that function from your page with `base44.functions.invoke()`. * * ## Billing and limits * From 995170e1de0c45e2dbb7e8ebce33e8ffafa920ba Mon Sep 17 00:00:00 2001 From: yardend Date: Wed, 14 Oct 2026 11:51:09 +0300 Subject: [PATCH 2/3] docs(ai-gateway): state the rule as server-side with the app's service role Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/sdk/src/modules/ai-gateway.types.ts | 28 +++++++++----------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/packages/sdk/src/modules/ai-gateway.types.ts b/packages/sdk/src/modules/ai-gateway.types.ts index 319394c0..c0f07a0d 100644 --- a/packages/sdk/src/modules/ai-gateway.types.ts +++ b/packages/sdk/src/modules/ai-gateway.types.ts @@ -7,8 +7,7 @@ export interface AiGatewayConnection { /** * Bearer token that authenticates the request: the service-role token from * `base44.asServiceRole.aiGateway`, or the signed-in user's token from - * `base44.aiGateway`. The user token is an empty string when no one is signed - * in, and the gateway rejects that call. + * `base44.aiGateway`. The gateway expects the service-role token. */ token: string; /** @@ -96,21 +95,20 @@ export interface AiGatewayModuleConfig { * * The mode determines which token `connection()` returns: * - * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. - * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. + * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the app's service-role token. + * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. The gateway accepts it only on apps shared privately or with your workspace. * - * Use service role from a backend function, as every example here does. The - * gateway accepts a user token only on apps shared privately or with your - * workspace. It rejects anonymous calls, and user-token calls on public apps, - * with a `403` and the error code `ai_gateway_requires_service_role`, so a - * visitor can't spend your app's credits by calling the gateway from the - * browser. A user-token call therefore works while you're building and starts - * failing the moment you share the app publicly. Service role also works when - * there's no signed-in user at all, such as from a scheduled automation. + * Call the gateway server-side with the app's service role, as every example + * here does. Calls from the browser or with a user's token are rejected with a + * `403`, the error code `ai_gateway_requires_service_role`, and the message + * "AI gateway requests must be made server-side using the app's service role. + * Calls from the browser or with a user's token are not allowed." Service role + * also works when there's no signed-in user at all, such as from a scheduled + * automation. * - * To control who triggers a billed request, check the caller with - * `base44.auth.me()` in your backend function before calling the gateway, and - * call that function from your page with `base44.functions.invoke()`. + * In a backend function, for example, you can check the caller with + * `base44.auth.me()` before calling the gateway, and call the function from + * your page with `base44.functions.invoke()`. * * ## Billing and limits * From 36d4aa619b5f074979d42128338b336f32718329 Mon Sep 17 00:00:00 2001 From: yardend Date: Wed, 14 Oct 2026 13:42:25 +0300 Subject: [PATCH 3/3] docs(ai-gateway): trim Authentication Modes to two bullets Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/sdk/src/modules/ai-gateway.types.ts | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/packages/sdk/src/modules/ai-gateway.types.ts b/packages/sdk/src/modules/ai-gateway.types.ts index c0f07a0d..0585a974 100644 --- a/packages/sdk/src/modules/ai-gateway.types.ts +++ b/packages/sdk/src/modules/ai-gateway.types.ts @@ -95,21 +95,9 @@ export interface AiGatewayModuleConfig { * * The mode determines which token `connection()` returns: * - * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the app's service-role token. + * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the app's service-role token. Use it server-side; the gateway rejects other calls with a `403` and the error code `ai_gateway_requires_service_role`. It also works with no signed-in user, such as from a scheduled automation. * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. The gateway accepts it only on apps shared privately or with your workspace. * - * Call the gateway server-side with the app's service role, as every example - * here does. Calls from the browser or with a user's token are rejected with a - * `403`, the error code `ai_gateway_requires_service_role`, and the message - * "AI gateway requests must be made server-side using the app's service role. - * Calls from the browser or with a user's token are not allowed." Service role - * also works when there's no signed-in user at all, such as from a scheduled - * automation. - * - * In a backend function, for example, you can check the caller with - * `base44.auth.me()` before calling the gateway, and call the function from - * your page with `base44.functions.invoke()`. - * * ## Billing and limits * * Requests are billed to your app's credit quota, which is the same shared