fix: api-reports

Signed-off-by: Juan Pablo Garcia Ripa <sarabadu@gmail.com>

packages/backend-defaults/report-auth.api.md

@@ -5,7 +5,7 @@
 ```ts
 import { AuthService } from '@backstage/backend-plugin-api';
 import { BackstagePrincipalAccessRestrictions } from '@backstage/backend-plugin-api';
-import { Config } from '@backstage/config';
+import type { Config } from '@backstage/config';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 
@@ -22,9 +22,32 @@ export const authServiceFactory: ServiceFactory<
   'singleton'
 >;
 
+// @public
+export function createExternalTokenHandler<TContext>(
+  handler: ExternalTokenHandler<TContext>,
+): ExternalTokenHandler<TContext>;
+
+// @public
+export interface ExternalTokenHandler<TContext> {
+  // (undocumented)
+  initialize(ctx: { options: Config }): TContext;
+  // (undocumented)
+  type: string;
+  // (undocumented)
+  verifyToken(
+    token: string,
+    ctx: TContext,
+  ): Promise<
+    | {
+        subject: string;
+      }
+    | undefined
+  >;
+}
+
 // @public
 export const externalTokenTypeHandlersRef: ServiceRef<
-  TokenTypeHandler,
+  ExternalTokenHandler<unknown>,
   'plugin',
   'multiton'
 >;
@@ -59,24 +82,5 @@ export const pluginTokenHandlerDecoratorServiceRef: ServiceRef<
   'singleton'
 >;
 
-// @public
-export interface ExternalTokenHandler {
-  // (undocumented)
-  verifyToken(token: string): Promise<
-    | {
-        subject: string;
-        allAccessRestrictions?: AccessRestrictionsMap;
-      }
-    | undefined
-  >;
-}
-
-// @public
-export interface TokenTypeHandler {
-  factory: (configs: Config[]) => TokenHandler | TokenHandler[];
-  // (undocumented)
-  type: string;
-}
-
 // (No @packageDocumentation comment for this package)
 ```

packages/backend-defaults/src/entrypoints/auth/external/helpers.ts

@@ -148,6 +148,34 @@ function readPermissionAttributes(externalAccessEntryConfig: Config) {
   return Object.keys(result).length ? result : undefined;
 }
 
+/**
+ * Creates an external token handler with the provided implementation.
+ *
+ * This helper function simplifies the creation of external token handlers by
+ * providing type safety and a consistent API. External token handlers are used
+ * to validate tokens from external systems that need to authenticate with Backstage.
+ *
+ * See {@link https://backstage.io/docs/auth/service-to-service-auth#adding-custom-externaltokenhandler | the service-to-service auth docs}
+ * for more information about implementing custom external token handlers.
+ *
+ * @public
+ * @param handler - The external token handler implementation with type, initialize, and verifyToken methods
+ * @returns The same handler instance, typed as ExternalTokenHandler<TContext>
+ *
+ * @example
+ * ```ts
+ * const customHandler = createExternalTokenHandler({
+ *   type: 'custom',
+ *   initialize({ options }) {
+ *     return { apiKey: options.getString('apiKey') };
+ *   },
+ *   async verifyToken(token, context) {
+ *     // Custom validation logic here
+ *     return { subject: 'custom:user' };
+ *   },
+ * });
+ * ```
+ */
 export function createExternalTokenHandler<TContext>(
   handler: ExternalTokenHandler<TContext>,
 ): ExternalTokenHandler<TContext> {