@logto/api 1.43.0 → 1.44.0-beta.1

package/README.md

@@ -27,30 +27,74 @@ For detailed setup instructions, visit: https://a.logto.io/m2m-mapi
 ```ts
 import { createManagementApi } from '@logto/api/management';
 
-// For Logto Cloud
-const { apiClient } = createManagementApi('your-tenant-id', {
+const { apiClient } = createManagementApi({
+  tenantId: 'your-tenant-id',
   clientId: 'your-client-id',
   clientSecret: 'your-client-secret',
 });
 
-// Make API calls
-const response = await apiClient.GET('/api/users');
+// Make API calls with lowercase or uppercase methods
+const response = await apiClient.get('/api/users');
+// const response = await apiClient.GET('/api/users');
 console.log(response.data);
 ```
 
+The positional `createManagementApi(tenantId, options)` form remains supported.
+
+#### Pagination
+
+Use `paginate()` to iterate over items from a paginated `GET` endpoint. The path, query parameters,
+path parameters, headers, and signal use the same generated types as `get()`.
+
+```ts
+for await (const user of apiClient.paginate('/api/users')) {
+  console.log(user);
+}
+```
+
+The iterator follows the Management API pagination headers and stops when there are no more items.
+It requests 100 items per page unless `page_size` is provided. When an audit log endpoint reports a
+capped total, the iterator continues until it receives an empty page because the final page is
+unknown. Breaking out of the loop stops further requests.
+
+API error responses throw `ManagementApiPaginationError`, which exposes `status`, response metadata
+and headers through `response`, and the parsed API error body as `cause`. The response body has
+already been read. Network, timeout, and abort errors propagate unchanged.
+
 #### Self-hosted / OSS
 
 ```ts
 import { createManagementApi } from '@logto/api/management';
 
-const { apiClient } = createManagementApi('default', {
+const { apiClient } = createManagementApi({
+  tenantId: 'default',
   clientId: 'your-client-id',
   clientSecret: 'your-client-secret',
   baseUrl: 'https://your-logto-instance.com',
-  apiIndicator: 'https://your-logto-instance.com/api',
 });
 ```
 
+If the Management API indicator cannot be derived from a tenant ID, omit `tenantId` and provide
+both `baseUrl` and `apiIndicator`.
+
+#### Timeouts
+
+Token fetches and Management API network requests have separate 10-second timeouts. The API request
+timeout starts after token retrieval, so a request that needs a new token can use both timeout
+periods. Use `tokenRequestTimeout` and `requestTimeout` to configure them in seconds. Set either option
+to `0` or a negative value to disable its timeout.
+
+Use `getTokenRequestSignal` to return a custom signal for each token request. The signal is composed
+with `tokenRequestTimeout`, and the first one to abort cancels the token request. A per-request
+`signal` is similarly composed with `requestTimeout` for the Management API request. Timeouts and
+custom cancellation reject the API call instead of returning a response object.
+
+#### Token refresh
+
+After a Management API request returns `401`, the next request fetches a new token. If the replacement
+token also receives a `401`, it remains cached until a request succeeds or the token expires. The SDK
+does not automatically retry the failed API request.
+
 #### Custom authentication
 
 For advanced use cases where you need full control over the authentication logic, use `createApiClient`:
@@ -67,7 +111,7 @@ const client = createApiClient({
 });
 
 // Type-safe API calls
-const response = await client.GET('/api/applications/{id}', {
+const response = await client.get('/api/applications/{id}', {
   params: { path: { id: 'your-app-id' } },
 });
 ```

package/lib/client-credentials.d.ts

@@ -6,7 +6,7 @@ export type AccessToken = {
     scope?: string;
 };
 export declare class ClientCredentialsError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export type ClientCredentialsOptions = {
     clientId: string;
@@ -15,9 +15,23 @@ export type ClientCredentialsOptions = {
     tokenParams?: Record<string, string>;
     /**
      * The time in seconds before the access token expires to consider it valid.
+     * A value greater than or equal to the token lifetime causes every call to fetch a new token,
+     * so cached-token invalidation protection cannot persist across calls.
      * @default 60
      */
     accessTokenExpiryLeeway?: Seconds;
+    /**
+     * The maximum time in seconds allowed for fetching an access token.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    tokenRequestTimeout?: Seconds;
+    /**
+     * Returns an optional signal for each token request. The factory is called once per actual token
+     * fetch, so concurrent callers sharing a fetch also share its signal. The signal is composed with
+     * `tokenRequestTimeout`, and the first signal to abort cancels the request.
+     */
+    getTokenRequestSignal?: () => AbortSignal | undefined;
 };
 /**
  * A class handles client credentials for API authentication. It caches the access token
@@ -26,12 +40,25 @@ export type ClientCredentialsOptions = {
 export declare class ClientCredentials {
     protected options: ClientCredentialsOptions;
     protected accessToken?: AccessToken;
+    private accessTokenPromise?;
+    private awaitingValidationAfterRefresh;
     get accessTokenExpiryLeeway(): Seconds;
+    get tokenRequestTimeout(): Seconds;
     constructor(options: ClientCredentialsOptions);
     /**
      * Retrieves the access token, refreshing it if necessary.
-     * @returns The access token as a string.
+     * Concurrent calls share the same token request.
+     * @returns The access token and its metadata.
      */
     getAccessToken(): Promise<AccessToken>;
+    /**
+     * Invalidates the cached token if it matches the token rejected by the API.
+     * A delayed response for an older token must not invalidate a newer cached token.
+     */
+    invalidateAccessToken(token: string): void;
+    /** Allows a future 401 to invalidate the token after it receives a successful API response. */
+    markAccessTokenAsValid(token: string): void;
+    private fetchAccessToken;
+    private requestAccessToken;
 }
 export {};

package/lib/client-credentials.js

@@ -1,9 +1,29 @@
+import { createTimeoutSignal, getAbortReason, normalizeTimeout } from './timeout.js';
 export class ClientCredentialsError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'ClientCredentialsError';
     }
 }
+const createAbortPromise = (signal) => {
+    // eslint-disable-next-line no-use-extend-native/no-use-extend-native -- `Promise.withResolvers` is standard since ES2024; the rule's built-in method list predates it.
+    const { promise, reject } = Promise.withResolvers();
+    const handleAbort = () => {
+        reject(getAbortReason(signal, 'Token request aborted'));
+    };
+    if (signal.aborted) {
+        handleAbort();
+    }
+    else {
+        signal.addEventListener('abort', handleAbort, { once: true });
+    }
+    return {
+        promise,
+        clear: () => {
+            signal.removeEventListener('abort', handleAbort);
+        },
+    };
+};
 /**
  * A class handles client credentials for API authentication. It caches the access token
  * and provides methods to retrieve it, ensuring the token is valid and refreshing it when necessary.
@@ -12,46 +32,113 @@ export class ClientCredentials {
     get accessTokenExpiryLeeway() {
         return this.options.accessTokenExpiryLeeway ?? 60;
     }
+    get tokenRequestTimeout() {
+        return normalizeTimeout(this.options.tokenRequestTimeout);
+    }
     constructor(options) {
         this.options = options;
+        this.awaitingValidationAfterRefresh = false;
     }
     /**
      * Retrieves the access token, refreshing it if necessary.
-     * @returns The access token as a string.
+     * Concurrent calls share the same token request.
+     * @returns The access token and its metadata.
      */
     async getAccessToken() {
         const now = new Date();
-        // If the access token is not set or has expired, refresh it
-        if (!this.accessToken?.expiresAt ||
-            this.accessToken.expiresAt <= Math.floor(now.getTime() / 1000) + this.accessTokenExpiryLeeway) {
-            const response = await fetch(this.options.tokenEndpoint, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                },
-                body: new URLSearchParams({
-                    grant_type: 'client_credentials',
-                    client_id: this.options.clientId,
-                    client_secret: this.options.clientSecret,
-                    ...this.options.tokenParams,
-                }).toString(),
-            });
-            if (!response.ok) {
-                throw new ClientCredentialsError(`Failed to fetch access token: ${response.status} ${response.statusText}`);
+        // Return the cached token if it is still valid.
+        if (this.accessToken?.expiresAt &&
+            this.accessToken.expiresAt > Math.floor(now.getTime() / 1000) + this.accessTokenExpiryLeeway) {
+            return this.accessToken;
+        }
+        if (this.accessToken) {
+            // A natural expiry starts a new invalidation cycle.
+            this.awaitingValidationAfterRefresh = false;
+        }
+        if (this.accessTokenPromise) {
+            return this.accessTokenPromise;
+        }
+        try {
+            this.accessTokenPromise = this.fetchAccessToken();
+            this.accessToken = await this.accessTokenPromise;
+            return this.accessToken;
+        }
+        finally {
+            this.accessTokenPromise = undefined;
+        }
+    }
+    /**
+     * Invalidates the cached token if it matches the token rejected by the API.
+     * A delayed response for an older token must not invalidate a newer cached token.
+     */
+    invalidateAccessToken(token) {
+        if (this.accessToken?.value === token && !this.awaitingValidationAfterRefresh) {
+            this.accessToken = undefined;
+            this.awaitingValidationAfterRefresh = true;
+        }
+    }
+    /** Allows a future 401 to invalidate the token after it receives a successful API response. */
+    markAccessTokenAsValid(token) {
+        if (this.accessToken?.value === token) {
+            this.awaitingValidationAfterRefresh = false;
+        }
+    }
+    async fetchAccessToken() {
+        const timeout = createTimeoutSignal(this.tokenRequestTimeout, 'Token request timed out');
+        try {
+            const customSignal = this.options.getTokenRequestSignal?.();
+            const signal = customSignal
+                ? AbortSignal.any([timeout.signal, customSignal])
+                : timeout.signal;
+            const abort = createAbortPromise(signal);
+            try {
+                // Guard against Response implementations that do not propagate request aborts to json().
+                return await Promise.race([this.requestAccessToken(signal), abort.promise]);
             }
-            const data = await response.json();
-            if (typeof data !== 'object' || data === null || !('access_token' in data)) {
-                throw new ClientCredentialsError('Invalid response from token endpoint');
+            finally {
+                abort.clear();
             }
-            if (!('expires_in' in data) || typeof data.expires_in !== 'number') {
-                throw new ClientCredentialsError('Invalid or missing expires_in in token response');
+        }
+        catch (error) {
+            if (error instanceof ClientCredentialsError) {
+                throw error;
             }
-            this.accessToken = {
-                value: String(data.access_token),
-                expiresAt: Math.floor(now.getTime() / 1000) + data.expires_in,
-                scope: 'scope' in data && typeof data.scope === 'string' ? data.scope : undefined,
-            };
+            throw new ClientCredentialsError(`Failed to fetch access token: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        finally {
+            timeout.clear();
+        }
+    }
+    async requestAccessToken(signal) {
+        const now = new Date();
+        const response = await fetch(this.options.tokenEndpoint, {
+            method: 'POST',
+            redirect: 'error',
+            signal,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: 'client_credentials',
+                client_id: this.options.clientId,
+                client_secret: this.options.clientSecret,
+                ...this.options.tokenParams,
+            }).toString(),
+        });
+        if (!response.ok) {
+            throw new ClientCredentialsError(`Failed to fetch access token: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (typeof data !== 'object' || data === null || !('access_token' in data)) {
+            throw new ClientCredentialsError('Invalid response from token endpoint');
+        }
+        if (!('expires_in' in data) || typeof data.expires_in !== 'number') {
+            throw new ClientCredentialsError('Invalid or missing expires_in in token response');
         }
-        return this.accessToken;
+        return {
+            value: String(data.access_token),
+            expiresAt: Math.floor(now.getTime() / 1000) + data.expires_in,
+            scope: 'scope' in data && typeof data.scope === 'string' ? data.scope : undefined,
+        };
     }
 }

package/lib/generated-types/management.js

@@ -1,5 +1 @@
-/**
- * This file was auto-generated by openapi-typescript.
- * Do not make direct changes to the file.
- */
 export {};

package/lib/management.d.ts

@@ -1,6 +1,8 @@
 import { type Client } from 'openapi-fetch';
 import { ClientCredentials } from './client-credentials.js';
 import { type paths } from './generated-types/management.js';
+import { type PaginateMethod } from './pagination.js';
+export { ManagementApiPaginationError } from './pagination.js';
 /**
  * Options for creating a Management API client.
  */
@@ -17,22 +19,52 @@ export type CreateManagementApiOptions = {
      */
     clientSecret: string;
     /**
-     * Override the base URL generated from the tenant ID.
-     * Useful for testing or custom deployments.
+     * The base URL for the Logto instance. Required when the tenant ID is omitted.
+     * Trailing slashes are ignored.
      */
     baseUrl?: string;
     /**
-     * Override the API indicator for the management API.
-     * Useful for testing or custom deployments.
+     * The resource indicator for the Management API. Required when the tenant ID is omitted.
      */
     apiIndicator?: string;
+    /**
+     * The maximum time in seconds allowed for fetching an access token.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    tokenRequestTimeout?: number;
+    /**
+     * Returns an optional signal for each token request. The factory is called once per actual token
+     * fetch, so concurrent callers sharing a fetch also share its signal. The signal is composed with
+     * `tokenRequestTimeout`, and the first signal to abort cancels the request.
+     */
+    getTokenRequestSignal?: () => AbortSignal | undefined;
+    /**
+     * The maximum time in seconds allowed for the Management API network request after token
+     * retrieval. It is composed with per-request signals, and a timeout rejects the API call.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    requestTimeout?: number;
 };
+/**
+ * Object options for creating a Management API client. Provide a tenant ID to derive the defaults,
+ * or provide both the base URL and API indicator directly.
+ */
+export type CreateManagementApiConfig = (CreateManagementApiOptions & {
+    tenantId: string;
+}) | (CreateManagementApiOptions & {
+    tenantId?: never;
+    baseUrl: string;
+    apiIndicator: string;
+});
 /**
  * Options for creating an API client with custom token authentication.
  */
 export type CreateApiClientOptions = {
     /**
      * The base URL for the Management API.
+     * Trailing slashes are ignored.
      */
     baseUrl: string;
     /**
@@ -40,6 +72,13 @@ export type CreateApiClientOptions = {
      * This function will be called for each request that requires authentication.
      */
     getToken: () => Promise<string>;
+    /**
+     * The maximum time in seconds allowed for the API network request after `getToken()` resolves.
+     * It is composed with per-request signals, and a timeout rejects the API call.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    requestTimeout?: number;
 };
 /**
  * Returns the base URL for the Management API based on the tenant ID.
@@ -59,6 +98,21 @@ export declare const getManagementApiIndicator: (tenantId: string) => string;
  * This is used when requesting an access token for the Management API.
  */
 export declare const allScope = "all";
+type LowercaseHttpMethods = {
+    get: Client<paths>['GET'];
+    put: Client<paths>['PUT'];
+    post: Client<paths>['POST'];
+    delete: Client<paths>['DELETE'];
+    options: Client<paths>['OPTIONS'];
+    head: Client<paths>['HEAD'];
+    patch: Client<paths>['PATCH'];
+    trace: Client<paths>['TRACE'];
+};
+type PaginationMethod = {
+    paginate: PaginateMethod<paths>;
+};
+/** A typed Management API client with lowercase HTTP methods and pagination support. */
+export type ManagementApiClient = Client<paths> & LowercaseHttpMethods & PaginationMethod;
 /**
  * Creates an API client with custom token authentication.
  *
@@ -78,12 +132,12 @@ export declare const allScope = "all";
  *   getToken: async () => getYourToken(),
  * });
  *
- * const response = await client.GET('/api/applications/{id}', {
+ * const response = await client.get('/api/applications/{id}', {
  *   params: { path: { id: 'app-id' } },
  * });
  * ```
  */
-export declare function createApiClient(options: CreateApiClientOptions): Client<paths>;
+export declare function createApiClient(options: CreateApiClientOptions): ManagementApiClient;
 type ManagementApiReturnType = {
     /**
      * The API client for the Management API.
@@ -91,14 +145,14 @@ type ManagementApiReturnType = {
      * This client is configured to use the provided client credentials
      * and will automatically include the access token in requests.
      */
-    apiClient: Client<paths>;
+    apiClient: ManagementApiClient;
     /**
      * The client credentials instance used for authentication.
      */
     clientCredentials: ClientCredentials;
 };
 /**
- * Creates a Management API client with the specified tenant ID and options.
+ * Creates a Management API client from a tenant ID or an explicit base URL and API indicator.
  *
  * Before using this function, ensure that you have created a machine-to-machine application in
  * Logto and granted it access to the Management API. See the documentation for more details:
@@ -108,35 +162,36 @@ type ManagementApiReturnType = {
  * This function sets up the API client with the necessary authentication using client credentials.
  * It will automatically handle token retrieval and renewal as needed.
  *
- * @param tenantId The tenant ID for which to create the Management API client. For OSS deployments,
- * you can pass any string as the tenant ID, for example, 'default'.
- * @param options The options for creating the Management API client, including client ID and secret.
+ * @param tenantIdOrConfig A tenant ID, or object options containing a tenant ID or an explicit base
+ * URL and API indicator.
+ * @param options The client options when the first argument is a tenant ID.
  * @returns An object containing the API client and client credentials instance.
  * @example
  * ```ts
  * import { createManagementApi } from '@logto/api/management';
  *
  * // Logto Cloud example
- * const { apiClient, clientCredentials } = createManagementApi('my-tenant-id', {
+ * const { apiClient, clientCredentials } = createManagementApi({
+ *   tenantId: 'my-tenant-id',
  *   clientId: 'my-client-id',
  *   clientSecret: 'my-client-secret',
  * });
  *
  * // Use apiClient to make requests to the Management API
- * const response = await apiClient.GET('/api/users');
+ * const response = await apiClient.get('/api/users');
  * console.log(response.data);
  * ```
  *
  * @example
  * ```ts
  * // OSS example
- * const { apiClient, clientCredentials } = createManagementApi('default', {
+ * const { apiClient, clientCredentials } = createManagementApi({
+ *   tenantId: 'default',
  *   clientId: 'my-client-id',
  *   clientSecret: 'my-client-secret',
  *   baseUrl: 'https://my-oss-logto-instance.com',
- *   apiIndicator: 'https://default.logto.app/api',
  * });
  * ```
  */
+export declare function createManagementApi(config: CreateManagementApiConfig): ManagementApiReturnType;
 export declare function createManagementApi(tenantId: string, options: CreateManagementApiOptions): ManagementApiReturnType;
-export {};

package/lib/management.js

@@ -1,5 +1,8 @@
 import createClient from 'openapi-fetch';
 import { ClientCredentials } from './client-credentials.js';
+import { createPaginate } from './pagination.js';
+import { normalizeTimeout, toTimeoutMilliseconds } from './timeout.js';
+export { ManagementApiPaginationError } from './pagination.js';
 /**
  * Returns the base URL for the Management API based on the tenant ID.
  * @param tenantId The tenant ID to construct the base URL.
@@ -18,6 +21,29 @@ export const getManagementApiIndicator = (tenantId) => `${getBaseUrl(tenantId)}/
  * This is used when requesting an access token for the Management API.
  */
 export const allScope = 'all';
+const bearerTokenPrefix = 'Bearer ';
+const normalizeBaseUrl = (baseUrl) => baseUrl.replace(/\/+$/u, '');
+const isWellKnownPath = (schemaPath) => schemaPath.includes('/.well-known/');
+const createRequestTimeoutFetch = (requestTimeout) => async (request, requestInit) => {
+    const signal = AbortSignal.any([
+        request.signal,
+        AbortSignal.timeout(toTimeoutMilliseconds(requestTimeout)),
+    ]);
+    return fetch(request, { ...requestInit, signal });
+};
+const addClientMethods = (client) => 
+// eslint-disable-next-line @silverhand/fp/no-mutating-assign -- Keep the original client identity while adding convenience methods.
+Object.assign(client, {
+    get: client.GET,
+    put: client.PUT,
+    post: client.POST,
+    delete: client.DELETE,
+    options: client.OPTIONS,
+    head: client.HEAD,
+    patch: client.PATCH,
+    trace: client.TRACE,
+    paginate: createPaginate(client.GET),
+});
 /**
  * Creates an API client with custom token authentication.
  *
@@ -37,71 +63,55 @@ export const allScope = 'all';
  *   getToken: async () => getYourToken(),
  * });
  *
- * const response = await client.GET('/api/applications/{id}', {
+ * const response = await client.get('/api/applications/{id}', {
  *   params: { path: { id: 'app-id' } },
  * });
  * ```
  */
 export function createApiClient(options) {
     const { baseUrl, getToken } = options;
-    const client = createClient({ baseUrl });
+    const requestTimeout = normalizeTimeout(options.requestTimeout);
+    const client = createClient({
+        baseUrl: normalizeBaseUrl(baseUrl),
+        ...(requestTimeout > 0 && { fetch: createRequestTimeoutFetch(requestTimeout) }),
+    });
     client.use({
         async onRequest({ schemaPath, request }) {
-            if (schemaPath.includes('/.well-known/')) {
+            if (isWellKnownPath(schemaPath)) {
                 return;
             }
             const token = await getToken();
-            request.headers.set('Authorization', `Bearer ${token}`);
+            request.headers.set('Authorization', `${bearerTokenPrefix}${token}`);
             return request;
         },
     });
-    return client;
+    return addClientMethods(client);
 }
-/**
- * Creates a Management API client with the specified tenant ID and options.
- *
- * Before using this function, ensure that you have created a machine-to-machine application in
- * Logto and granted it access to the Management API. See the documentation for more details:
- *
- * https://a.logto.io/m2m-mapi
- *
- * This function sets up the API client with the necessary authentication using client credentials.
- * It will automatically handle token retrieval and renewal as needed.
- *
- * @param tenantId The tenant ID for which to create the Management API client. For OSS deployments,
- * you can pass any string as the tenant ID, for example, 'default'.
- * @param options The options for creating the Management API client, including client ID and secret.
- * @returns An object containing the API client and client credentials instance.
- * @example
- * ```ts
- * import { createManagementApi } from '@logto/api/management';
- *
- * // Logto Cloud example
- * const { apiClient, clientCredentials } = createManagementApi('my-tenant-id', {
- *   clientId: 'my-client-id',
- *   clientSecret: 'my-client-secret',
- * });
- *
- * // Use apiClient to make requests to the Management API
- * const response = await apiClient.GET('/api/users');
- * console.log(response.data);
- * ```
- *
- * @example
- * ```ts
- * // OSS example
- * const { apiClient, clientCredentials } = createManagementApi('default', {
- *   clientId: 'my-client-id',
- *   clientSecret: 'my-client-secret',
- *   baseUrl: 'https://my-oss-logto-instance.com',
- *   apiIndicator: 'https://default.logto.app/api',
- * });
- * ```
- */
-export function createManagementApi(tenantId, options) {
-    const { clientId, clientSecret } = options;
-    const baseUrl = options.baseUrl ?? getBaseUrl(tenantId);
-    const apiIndicator = options.apiIndicator ?? getManagementApiIndicator(tenantId);
+const resolveManagementApiArguments = (tenantIdOrConfig, options) => {
+    if (typeof tenantIdOrConfig === 'string') {
+        if (!options) {
+            throw new TypeError('Options are required when creating a Management API client by tenant ID');
+        }
+        return { tenantId: tenantIdOrConfig, options };
+    }
+    if (!tenantIdOrConfig) {
+        throw new TypeError('Provide a tenant ID or both baseUrl and apiIndicator');
+    }
+    return { tenantId: tenantIdOrConfig.tenantId, options: tenantIdOrConfig };
+};
+export function createManagementApi(tenantIdOrConfig, options) {
+    const { tenantId, options: resolvedOptions } = resolveManagementApiArguments(tenantIdOrConfig, options);
+    if (tenantId !== undefined && tenantId.trim().length === 0) {
+        throw new TypeError('Tenant ID must not be empty');
+    }
+    const { clientId, clientSecret, tokenRequestTimeout, getTokenRequestSignal, requestTimeout } = resolvedOptions;
+    const configuredBaseUrl = resolvedOptions.baseUrl ?? (tenantId === undefined ? undefined : getBaseUrl(tenantId));
+    const apiIndicator = resolvedOptions.apiIndicator ??
+        (tenantId === undefined ? undefined : getManagementApiIndicator(tenantId));
+    if (configuredBaseUrl === undefined || apiIndicator === undefined) {
+        throw new TypeError('Provide a tenant ID or both baseUrl and apiIndicator');
+    }
+    const baseUrl = normalizeBaseUrl(configuredBaseUrl);
     const clientCredentials = new ClientCredentials({
         clientId,
         clientSecret,
@@ -110,17 +120,41 @@ export function createManagementApi(tenantId, options) {
             resource: apiIndicator,
             scope: allScope,
         },
+        tokenRequestTimeout,
+        getTokenRequestSignal,
     });
+    const warnedScopes = new Set();
     const apiClient = createApiClient({
         baseUrl,
+        requestTimeout,
         getToken: async () => {
             const { value, scope } = await clientCredentials.getAccessToken();
-            if (scope !== allScope) {
+            if (scope !== allScope && !warnedScopes.has(scope)) {
+                warnedScopes.add(scope);
                 console.warn(`The scope "${scope}" is not equal to the expected value "${allScope}". This may cause issues with API access. See https://a.logto.io/m2m-mapi to learn more about configuring machine-to-machine access to the Management API.`);
             }
             return value;
         },
     });
+    apiClient.use({
+        onResponse({ schemaPath, request, response }) {
+            if (isWellKnownPath(schemaPath)) {
+                return;
+            }
+            const authorization = request.headers.get('Authorization');
+            if (!authorization?.startsWith(bearerTokenPrefix)) {
+                return;
+            }
+            const accessToken = authorization.slice(bearerTokenPrefix.length);
+            if (response.status === 401) {
+                // Do not retry here because the request body may have been consumed.
+                clientCredentials.invalidateAccessToken(accessToken);
+            }
+            else if (response.ok) {
+                clientCredentials.markAccessTokenAsValid(accessToken);
+            }
+        },
+    });
     return {
         apiClient,
         clientCredentials,

package/lib/pagination.d.ts

@@ -0,0 +1,37 @@
+import type { Client, ClientPathsWithMethod, MaybeOptionalInit, MethodResponse } from 'openapi-fetch';
+type GetOperation<Paths extends NonNullable<unknown>, Path extends keyof Paths> = Paths[Path] extends {
+    get: infer Operation;
+} ? Operation : never;
+type OperationQuery<Operation> = Operation extends {
+    parameters: {
+        query?: infer Query;
+    };
+} ? NonNullable<Query> : never;
+type SupportsPagination<Operation> = [OperationQuery<Operation>] extends [never] ? false : 'page' extends keyof OperationQuery<Operation> ? 'page_size' extends keyof OperationQuery<Operation> ? true : false : false;
+type GetPath<Paths extends NonNullable<unknown>> = ClientPathsWithMethod<Client<Paths>, 'get'>;
+type PaginatedGetPath<Paths extends NonNullable<unknown>> = {
+    [Path in GetPath<Paths>]: SupportsPagination<GetOperation<Paths, Path>> extends true ? MethodResponse<Client<Paths>, 'get', Path> extends readonly unknown[] ? Path : never : never;
+}[GetPath<Paths>];
+type PaginationItem<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = MethodResponse<Client<Paths>, 'get', Path> extends ReadonlyArray<infer Item> ? Item : never;
+type GetInit<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = MaybeOptionalInit<{
+    get: GetOperation<Paths, Path>;
+}, 'get'>;
+type PaginationOptions<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = Omit<NonNullable<GetInit<Paths, Path>>, 'parseAs'> & {
+    parseAs?: never;
+};
+type PaginationInit<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = undefined extends GetInit<Paths, Path> ? [PaginationOptions<Paths, Path>?] : [PaginationOptions<Paths, Path>];
+/** Iterates over items returned by a paginated Management API GET endpoint. */
+export type PaginateMethod<Paths extends NonNullable<unknown>> = <Path extends PaginatedGetPath<Paths>>(path: Path, ...init: PaginationInit<Paths, Path>) => AsyncGenerator<PaginationItem<Paths, Path>, void, undefined>;
+/** An error response returned while iterating over a paginated Management API endpoint. */
+export declare class ManagementApiPaginationError extends Error {
+    /**
+     * The error response metadata and headers. Its body has already been read by openapi-fetch; the
+     * parsed error body is available as `cause`.
+     */
+    readonly response: Response;
+    readonly status: number;
+    constructor(response: Response, options?: ErrorOptions);
+}
+/** Creates a typed pagination method backed by an openapi-fetch GET method. */
+export declare const createPaginate: <Paths extends NonNullable<unknown>>(get: Client<Paths>["GET"]) => PaginateMethod<Paths>;
+export {};

package/lib/pagination.js

@@ -0,0 +1,66 @@
+const defaultPageSize = 100;
+const hasNextLink = (headers) => headers
+    .get('Link')
+    ?.split(',')
+    .some((link) => /;\s*rel=(?:"next"|next)(?:\s*;|\s*$)/iu.test(link.trim())) ?? false;
+const isTotalNumberCapped = (headers) => headers.get('Total-Number-Is-Capped')?.toLowerCase() === 'true';
+/** An error response returned while iterating over a paginated Management API endpoint. */
+export class ManagementApiPaginationError extends Error {
+    constructor(response, options) {
+        super(`Management API pagination request failed with status ${response.status}`, options);
+        this.name = 'ManagementApiPaginationError';
+        this.response = response;
+        this.status = response.status;
+    }
+}
+/** Creates a typed pagination method backed by an openapi-fetch GET method. */
+export const createPaginate = (get) => {
+    // eslint-disable-next-line no-restricted-syntax -- The runtime adapter narrows openapi-fetch's generic GET method after the public type validates the path and options.
+    const getPage = get;
+    const paginate = (path, options = {}) => {
+        const { params = {}, parseAs, ...requestOptions } = options;
+        if (parseAs !== undefined) {
+            throw new TypeError('The paginate method only supports JSON array responses');
+        }
+        const query = params.query ?? {};
+        const firstPage = query.page === undefined ? 1 : query.page;
+        if (typeof firstPage !== 'number' || !Number.isSafeInteger(firstPage) || firstPage < 1) {
+            throw new RangeError('The page parameter must be a positive safe integer');
+        }
+        const pageSize = query.page_size ?? defaultPageSize;
+        const iterate = async function* () {
+            /* eslint-disable-next-line @silverhand/fp/no-let, @silverhand/fp/no-mutation -- Pagination advances one page at a time without retaining prior page responses. */
+            for (let page = firstPage; page <= Number.MAX_SAFE_INTEGER; page += 1) {
+                // eslint-disable-next-line no-await-in-loop -- Each request depends on the previous response's pagination headers.
+                const result = await getPage(path, {
+                    ...requestOptions,
+                    params: {
+                        ...params,
+                        query: {
+                            ...query,
+                            page,
+                            page_size: pageSize,
+                        },
+                    },
+                });
+                if ('error' in result) {
+                    throw new ManagementApiPaginationError(result.response, { cause: result.error });
+                }
+                if (!Array.isArray(result.data)) {
+                    throw new TypeError('Expected a paginated Management API response to contain an array');
+                }
+                if (result.data.length === 0) {
+                    return;
+                }
+                yield* result.data;
+                if (!isTotalNumberCapped(result.response.headers) &&
+                    !hasNextLink(result.response.headers)) {
+                    return;
+                }
+            }
+        };
+        return iterate();
+    };
+    // eslint-disable-next-line no-restricted-syntax -- The public generic type adds generated path and item types to the runtime iterator.
+    return paginate;
+};

package/lib/timeout.d.ts

@@ -0,0 +1,7 @@
+export declare const normalizeTimeout: (timeout?: number) => number;
+export declare const getAbortReason: (signal: AbortSignal, fallbackMessage: string) => Error;
+export declare const toTimeoutMilliseconds: (timeout: number) => number;
+export declare const createTimeoutSignal: (timeout: number, message: string) => {
+    signal: AbortSignal;
+    clear: () => void;
+};

package/lib/timeout.js

@@ -0,0 +1,29 @@
+const defaultTimeout = 10;
+// Browsers and Node.js reliably support timer delays up to a signed 32-bit integer.
+const maximumTimeoutMilliseconds = 2_147_483_647;
+export const normalizeTimeout = (timeout) => {
+    if (timeout === undefined || Number.isNaN(timeout)) {
+        return defaultTimeout;
+    }
+    return Number.isFinite(timeout) && timeout > 0 ? timeout : 0;
+};
+export const getAbortReason = (signal, fallbackMessage) => {
+    // eslint-disable-next-line prefer-destructuring -- Keep the DOM's any-typed reason narrowed to unknown.
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error(fallbackMessage, { cause: reason });
+};
+export const toTimeoutMilliseconds = (timeout) => Math.min(Math.max(Math.ceil(timeout * 1000), 1), maximumTimeoutMilliseconds);
+export const createTimeoutSignal = (timeout, message) => {
+    const controller = new AbortController();
+    const timer = timeout > 0
+        ? setTimeout(() => {
+            controller.abort(new DOMException(message, 'TimeoutError'));
+        }, toTimeoutMilliseconds(timeout))
+        : undefined;
+    return {
+        signal: controller.signal,
+        clear: () => {
+            clearTimeout(timer);
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/api",
-  "version": "1.43.0",
+  "version": "1.44.0-beta.1",
   "description": "Logto API types and clients.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",
@@ -26,6 +26,18 @@
   "bugs": {
     "url": "https://github.com/logto-io/logto/issues"
   },
+  "scripts": {
+    "precommit": "lint-staged",
+    "prepublishOnly": "pnpm generate-types && pnpm build",
+    "generate-types": "./generate-types.sh",
+    "build": "./check-types.sh && rm -rf lib/ && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "lint": "eslint --ext .ts src",
+    "lint:report": "pnpm lint --format json --output-file report.json",
+    "test": "vitest run src",
+    "test:watch": "vitest src --watch",
+    "test:ci": "pnpm run test --silent --coverage"
+  },
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
   },
@@ -49,15 +61,5 @@
     ],
     "extends": "@silverhand"
   },
-  "prettier": "@silverhand/eslint-config/.prettierrc",
-  "scripts": {
-    "precommit": "lint-staged",
-    "generate-types": "./generate-types.sh",
-    "build": "./check-types.sh && rm -rf lib/ && tsc -p tsconfig.build.json",
-    "lint": "eslint --ext .ts src",
-    "lint:report": "pnpm lint --format json --output-file report.json",
-    "test": "vitest run src",
-    "test:watch": "vitest src --watch",
-    "test:ci": "pnpm run test --silent --coverage"
-  }
-}
+  "prettier": "@silverhand/eslint-config/.prettierrc"
+}