Backstage
    Preparing search index...

    Allows plugins to register HTTP routes.

    See the service documentation for more details.

    interface HttpRouterService {
        addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
        addWebSocketHandler(options: HttpRouterServiceWebSocketHandler): void;
        use(handler: Handler): void;
    }
    Index
    • Adds an auth policy to the router. This is used to allow unauthenticated or cookie based access to parts of a plugin's API.

      Parameters

      Returns void

      The paths given follow the same pattern as the routers given to the use method, that is, they are relative to the plugin's base URL, and can contain placeholders.

      http.addAuthPolicy({
      path: '/static/:id',
      allow: 'user-cookie',
      });

      This allows limited access tokens via cookies on the /api/<plugin-id>/static/* paths, but not unauthenticated access.

    • Registers a WebSocket upgrade handler at an exact plugin-relative path. Paths must start with /. Matching is case-sensitive, ignores the query string, and treats a trailing slash as significant. Patterns are not supported.

      The handler receives the raw upgrade request, socket, and buffered data. The framework waits for plugin startup and authenticates before invoking the handler, rejecting upgrades during shutdown. The handler owns the handshake or forwarding, including protocol selection. HTTP middleware, including rate limiting and request logging, and path-based auth policies do not apply, even when the route uses authPolicy: 'unauthenticated'. Existing upgrade handlers that rely on Express routing must migrate to registered routes. The framework destroys upgraded sockets when the backend shuts down.

      Returns void