diff --git a/docs/reference/.generated b/docs/reference/.generated
new file mode 100644
index 0000000000..e08947a827
--- /dev/null
+++ b/docs/reference/.generated
@@ -0,0 +1,2 @@
+The contents of this folder is generated by the root `yarn build:api-docs` command.
+Don't put any additional content here as it will be overwritten during the microsite build.
diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md
deleted file mode 100644
index d550ba10a9..0000000000
--- a/docs/reference/createPlugin-feature-flags.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-id: createPlugin-feature-flags
-title: createPlugin - feature flags
-description: Documentation on createPlugin - feature flags
----
-
-The `featureFlags` object passed to the `register` function makes it possible
-for plugins to register Feature Flags in Backstage for users to opt into. You
-can use this to split out logic in your code for manual A/B testing, etc.
-
-Here's a code sample:
-
-```typescript
-import { createPlugin } from '@backstage/core-plugin-api';
-
-export default createPlugin({
- id: 'plugin-name',
- register({ featureFlags }) {
- featureFlags.register('enable-example-feature');
- },
-});
-```
-
-## Using with useApi
-
-To inspect the state of a feature flag inside your plugin, you can use the
-`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example:
-
-```tsx
-import React from 'react';
-import { Button } from '@material-ui/core';
-import { featureFlagsApiRef, useApi } from '@backstage/core-plugin-api';
-
-const ExamplePage = () => {
- const featureFlags = useApi(featureFlagsApiRef);
-
- return (
-
-
- { featureFlags.isActive('enable-example-feature') && }
-
- );
-};
-```
diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md
deleted file mode 100644
index 6602b0b2cc..0000000000
--- a/docs/reference/createPlugin.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-id: createPlugin
-title: createPlugin
-description: Documentation on createPlugin
----
-
-Takes a plugin config as an argument and returns a new plugin.
-
-## Plugin Config
-
-```typescript
-function createPlugin(config: PluginConfig): BackstagePlugin;
-
-type PluginConfig = {
- id: string;
- register?(hooks: PluginHooks): void;
-};
-
-type PluginHooks = {
- featureFlags: FeatureFlagsHooks;
-};
-```
-
-- [Read more about feature flags here](createPlugin-feature-flags.md)
-
-## Example Uses
-
-### Creating a basic plugin
-
-Showcasing adding a feature flag.
-
-```jsx
-import { createPlugin } from '@backstage/core-plugin-api';
-
-export default createPlugin({
- id: 'new-plugin',
- register({ router, featureFlags }) {
- featureFlags.register('enable-example-component');
- },
-});
-```
diff --git a/docs/reference/utility-apis/AlertApi.md b/docs/reference/utility-apis/AlertApi.md
deleted file mode 100644
index 8d1851cc44..0000000000
--- a/docs/reference/utility-apis/AlertApi.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# AlertApi
-
-The AlertApi type is defined at
-[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L29).
-
-The following Utility API implements this type: [alertApiRef](./README.md#alert)
-
-## Members
-
-### post()
-
-Post an alert for handling by the application.
-
-
-post(alert: AlertMessage): void
-
-
-### alert\$()
-
-Observe alerts posted by other parts of the application.
-
-
-alert$(): Observable<AlertMessage>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AlertMessage
-
-
-export type AlertMessage = {
- message: string;
- // Severity will default to success since that is what material ui defaults the value to.
- severity?: 'success' | 'info' | 'warning' | 'error';
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/AlertApi.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L19).
-
-Referenced by: [post](#post), [alert\$](#alert).
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [alert\$](#alert).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/AppThemeApi.md b/docs/reference/utility-apis/AppThemeApi.md
deleted file mode 100644
index a662b4cb70..0000000000
--- a/docs/reference/utility-apis/AppThemeApi.md
+++ /dev/null
@@ -1,271 +0,0 @@
-# AppThemeApi
-
-The AppThemeApi type is defined at
-[packages/core-api/src/apis/definitions/AppThemeApi.ts:56](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L56).
-
-The following Utility API implements this type:
-[appThemeApiRef](./README.md#apptheme)
-
-## Members
-
-### getInstalledThemes()
-
-Get a list of available themes.
-
-
-getInstalledThemes(): AppTheme[]
-
-
-### activeThemeId\$()
-
-Observe the currently selected theme. A value of undefined means no specific
-theme has been selected.
-
-
-activeThemeId$(): Observable<string | undefined>
-
-
-### getActiveThemeId()
-
-Get the current theme ID. Returns undefined if no specific theme is selected.
-
-
-getActiveThemeId(): string | undefined
-
-
-### setActiveThemeId()
-
-Set a specific theme to use in the app, overriding the default theme selection.
-
-Clear the selection by passing in undefined.
-
-
-setActiveThemeId(themeId?: string): void
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AppTheme
-
-Describes a theme provided by the app.
-
-
-export type AppTheme = {
- /**
- * ID used to remember theme selections.
- */
- id: string;
-
- /**
- * Title of the theme
- */
- title: string;
-
- /**
- * Theme variant
- */
- variant: 'light' | 'dark';
-
- /**
- * The specialized MaterialUI theme instance.
- */
- theme: BackstageTheme;
-
- /**
- * An Icon for the theme mode setting.
- */
- icon?: React.ReactElement<SvgIconProps>;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/AppThemeApi.ts:25](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L25).
-
-Referenced by: [getInstalledThemes](#getinstalledthemes).
-
-### BackstagePalette
-
-
-export type BackstagePalette = Palette & PaletteAdditions
-
-
-Defined at
-[packages/theme/src/types.ts:74](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L74).
-
-Referenced by: [BackstageTheme](#backstagetheme).
-
-### BackstageTheme
-
-
-export interface BackstageTheme extends Theme {
- palette: BackstagePalette;
- page: PageTheme;
- getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
-}
-
-
-Defined at
-[packages/theme/src/types.ts:81](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L81).
-
-Referenced by: [AppTheme](#apptheme).
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [activeThemeId\$](#activethemeid).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### PageTheme
-
-
-export type PageTheme = {
- colors: string[];
- shape: string;
- backgroundImage: string;
-}
-
-
-Defined at
-[packages/theme/src/types.ts:103](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L103).
-
-Referenced by: [BackstageTheme](#backstagetheme).
-
-### PageThemeSelector
-
-
-export type PageThemeSelector = {
- themeId: string;
-}
-
-
-Defined at
-[packages/theme/src/types.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L77).
-
-Referenced by: [BackstageTheme](#backstagetheme).
-
-### PaletteAdditions
-
-
-type PaletteAdditions = {
- status: {
- ok: string;
- warning: string;
- error: string;
- pending: string;
- running: string;
- aborted: string;
- };
- border: string;
- textContrast: string;
- textVerySubtle: string;
- textSubtle: string;
- highlight: string;
- errorBackground: string;
- warningBackground: string;
- infoBackground: string;
- errorText: string;
- infoText: string;
- warningText: string;
- linkHover: string;
- link: string;
- gold: string;
- navigation: {
- background: string;
- indicator: string;
- color: string;
- selectedColor: string;
- };
- tabbar: {
- indicator: string;
- };
- bursts: {
- fontColor: string;
- slackChannelText: string;
- backgroundColor: {
- default: string;
- };
- };
- pinSidebarButton: {
- icon: string;
- background: string;
- };
- banner: {
- info: string;
- error: string;
- text: string;
- link: string;
- };
-}
-
-
-Defined at
-[packages/theme/src/types.ts:23](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L23).
-
-Referenced by: [BackstagePalette](#backstagepalette).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/BackstageIdentityApi.md b/docs/reference/utility-apis/BackstageIdentityApi.md
deleted file mode 100644
index 80a40d427e..0000000000
--- a/docs/reference/utility-apis/BackstageIdentityApi.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# BackstageIdentityApi
-
-The BackstageIdentityApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L134).
-
-The following Utility APIs implement this type:
-
-- [auth0AuthApiRef](./README.md#auth0auth)
-
-- [githubAuthApiRef](./README.md#githubauth)
-
-- [gitlabAuthApiRef](./README.md#gitlabauth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oidcAuthApiRef](./README.md#oidcauth)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-- [oneloginAuthApiRef](./README.md#oneloginauth)
-
-- [samlAuthApiRef](./README.md#samlauth)
-
-## Members
-
-### getBackstageIdentity()
-
-Get the user's identity within Backstage. This should normally not be called
-directly, use the @IdentityApi instead.
-
-If the optional flag is not set, a session is guaranteed to be returned, while
-if the optional flag is set, the session may be undefined. See
-@AuthRequestOptions for more details.
-
-
-getBackstageIdentity(
- options?: AuthRequestOptions,
- ): Promise<BackstageIdentity | undefined>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AuthRequestOptions
-
-
-export type AuthRequestOptions = {
- /**
- * If this is set to true, the user will not be prompted to log in,
- * and an empty response will be returned if there is no existing session.
- *
- * This can be used to perform a check whether the user is logged in, or if you don't
- * want to force a user to be logged in, but provide functionality if they already are.
- *
- * @default false
- */
- optional?: boolean;
-
- /**
- * If this is set to true, the request will bypass the regular oauth login modal
- * and open the login popup directly.
- *
- * The method must be called synchronously from a user action for this to work in all browsers.
- *
- * @default false
- */
- instantPopup?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
-
-Referenced by: [getBackstageIdentity](#getbackstageidentity).
-
-### BackstageIdentity
-
-
-export type BackstageIdentity = {
- /**
- * The backstage user ID.
- */
- id: string;
-
- /**
- * An ID token that can be used to authenticate the user within Backstage.
- */
- idToken: string;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L147).
-
-Referenced by: [getBackstageIdentity](#getbackstageidentity).
diff --git a/docs/reference/utility-apis/Config.md b/docs/reference/utility-apis/Config.md
deleted file mode 100644
index c5b20610e7..0000000000
--- a/docs/reference/utility-apis/Config.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Config
-
-The Config type is defined at
-[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32).
-
-The following Utility API implements this type:
-[configApiRef](./README.md#config)
-
-## Members
-
-### has()
-
-
-has(key: string): boolean
-
-
-### keys()
-
-
-keys(): string[]
-
-
-### get()
-
-
-get(key?: string): JsonValue
-
-
-### getOptional()
-
-
-getOptional(key?: string): JsonValue | undefined
-
-
-### getConfig()
-
-
-getConfig(key: string): Config
-
-
-### getOptionalConfig()
-
-
-getOptionalConfig(key: string): Config | undefined
-
-
-### getConfigArray()
-
-
-getConfigArray(key: string): Config[]
-
-
-### getOptionalConfigArray()
-
-
-getOptionalConfigArray(key: string): Config[] | undefined
-
-
-### getNumber()
-
-
-getNumber(key: string): number
-
-
-### getOptionalNumber()
-
-
-getOptionalNumber(key: string): number | undefined
-
-
-### getBoolean()
-
-
-getBoolean(key: string): boolean
-
-
-### getOptionalBoolean()
-
-
-getOptionalBoolean(key: string): boolean | undefined
-
-
-### getString()
-
-
-getString(key: string): string
-
-
-### getOptionalString()
-
-
-getOptionalString(key: string): string | undefined
-
-
-### getStringArray()
-
-
-getStringArray(key: string): string[]
-
-
-### getOptionalStringArray()
-
-
-getOptionalStringArray(key: string): string[] | undefined
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### Config
-
-
-export type Config = {
- has(key: string): boolean;
-
- keys(): string[];
-
- get(key?: string): JsonValue;
- getOptional(key?: string): JsonValue | undefined;
-
- getConfig(key: string): Config;
- getOptionalConfig(key: string): Config | undefined;
-
- getConfigArray(key: string): Config[];
- getOptionalConfigArray(key: string): Config[] | undefined;
-
- getNumber(key: string): number;
- getOptionalNumber(key: string): number | undefined;
-
- getBoolean(key: string): boolean;
- getOptionalBoolean(key: string): boolean | undefined;
-
- getString(key: string): string;
- getOptionalString(key: string): string | undefined;
-
- getStringArray(key: string): string[];
- getOptionalStringArray(key: string): string[] | undefined;
-}
-
-
-Defined at
-[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32).
-
-Referenced by: [getConfig](#getconfig), [getOptionalConfig](#getoptionalconfig),
-[getConfigArray](#getconfigarray),
-[getOptionalConfigArray](#getoptionalconfigarray), [Config](#config).
-
-### JsonArray
-
-
-export type JsonArray = JsonValue[]
-
-
-Defined at
-[packages/config/src/types.ts:18](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L18).
-
-Referenced by: [JsonValue](#jsonvalue).
-
-### JsonObject
-
-
-export type JsonObject = { [key in string]?: JsonValue }
-
-
-Defined at
-[packages/config/src/types.ts:17](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L17).
-
-Referenced by: [JsonValue](#jsonvalue).
-
-### JsonValue
-
-
-export type JsonValue =
- | JsonObject
- | JsonArray
- | number
- | string
- | boolean
- | null
-
-
-Defined at
-[packages/config/src/types.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L19).
-
-Referenced by: [get](#get), [getOptional](#getoptional),
-[JsonObject](#jsonobject), [JsonArray](#jsonarray), [Config](#config).
diff --git a/docs/reference/utility-apis/DiscoveryApi.md b/docs/reference/utility-apis/DiscoveryApi.md
deleted file mode 100644
index 0d888c1daa..0000000000
--- a/docs/reference/utility-apis/DiscoveryApi.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# DiscoveryApi
-
-The DiscoveryApi type is defined at
-[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30).
-
-The following Utility API implements this type:
-[discoveryApiRef](./README.md#discovery)
-
-## Members
-
-### getBaseUrl()
-
-Returns the HTTP base backend URL for a given plugin, without a trailing slash.
-
-This method must always be called just before making a request, as opposed to
-fetching the URL when constructing an API client. That is to ensure that more
-flexible routing patterns can be supported.
-
-For example, asking for the URL for `auth` may return something like
-`https://backstage.example.com/api/auth`
-
-
-getBaseUrl(pluginId: string): Promise<string>
-
diff --git a/docs/reference/utility-apis/ErrorApi.md b/docs/reference/utility-apis/ErrorApi.md
deleted file mode 100644
index 1aaecdb47e..0000000000
--- a/docs/reference/utility-apis/ErrorApi.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# ErrorApi
-
-The ErrorApi type is defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L53).
-
-The following Utility API implements this type: [errorApiRef](./README.md#error)
-
-## Members
-
-### post()
-
-Post an error for handling by the application.
-
-
-post(error: Error, context?: ErrorContext): void
-
-
-### error\$()
-
-Observe errors posted by other parts of the application.
-
-
-error$(): Observable<{ error: Error; context?: ErrorContext }>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### Error
-
-Mirrors the JavaScript Error class, for the purpose of providing documentation
-and optional fields.
-
-
-type Error = {
- name: string;
- message: string;
- stack?: string;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L24).
-
-Referenced by: [post](#post), [error\$](#error).
-
-### ErrorContext
-
-Provides additional information about an error that was posted to the
-application.
-
-
-export type ErrorContext = {
- // If set to true, this error should not be displayed to the user. Defaults to false.
- hidden?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L33).
-
-Referenced by: [post](#post), [error\$](#error).
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [error\$](#error).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/FeatureFlagsApi.md b/docs/reference/utility-apis/FeatureFlagsApi.md
deleted file mode 100644
index 1e8979c02e..0000000000
--- a/docs/reference/utility-apis/FeatureFlagsApi.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# FeatureFlagsApi
-
-The FeatureFlagsApi type is defined at
-[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:60](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L60).
-
-The following Utility API implements this type:
-[featureFlagsApiRef](./README.md#featureflags)
-
-## Members
-
-### registerFlag()
-
-Registers a new feature flag. Once a feature flag has been registered it can be
-toggled by users, and read back to enable or disable features.
-
-
-registerFlag(flag: FeatureFlag): void
-
-
-### getRegisteredFlags()
-
-Get a list of all registered flags.
-
-
-getRegisteredFlags(): FeatureFlag[]
-
-
-### isActive()
-
-Whether the feature flag with the given name is currently activated for the
-user.
-
-
-isActive(name: string): boolean
-
-
-### save()
-
-Save the user's choice of feature flag states.
-
-
-save(options: FeatureFlagsSaveOptions): void
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### FeatureFlag
-
-The feature flags API is used to toggle functionality to users across plugins
-and Backstage.
-
-Plugins can use this API to register feature flags that they have available for
-users to enable/disable, and this API will centralize the current user's state
-of which feature flags they would like to enable.
-
-This is ideal for Backstage plugins, as well as your own App, to trial
-incomplete or unstable upcoming features. Although there will be a common
-interface for users to enable and disable feature flags, this API acts as
-another way to enable/disable.
-
-
-export type FeatureFlag = {
- name: string;
- pluginId: string;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L31).
-
-Referenced by: [registerFlag](#registerflag),
-[getRegisteredFlags](#getregisteredflags).
-
-### FeatureFlagState
-
-
-export enum FeatureFlagState {
- None = 0,
- Active = 1,
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:36](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L36).
-
-Referenced by: [FeatureFlagsSaveOptions](#featureflagssaveoptions).
-
-### FeatureFlagsSaveOptions
-
-Options to use when saving feature flags.
-
-
-export type FeatureFlagsSaveOptions = {
- /**
- * The new feature flag states to save.
- */
- states: Record<string, FeatureFlagState>;
-
- /**
- * Whether the saves states should be merged into the existing ones, or replace them.
- *
- * Defaults to false.
- */
- merge?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:44](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L44).
-
-Referenced by: [save](#save).
diff --git a/docs/reference/utility-apis/IdentityApi.md b/docs/reference/utility-apis/IdentityApi.md
deleted file mode 100644
index aa2a4dd9a0..0000000000
--- a/docs/reference/utility-apis/IdentityApi.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# IdentityApi
-
-The IdentityApi type is defined at
-[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L22).
-
-The following Utility API implements this type:
-[identityApiRef](./README.md#identity)
-
-## Members
-
-### getUserId()
-
-The ID of the signed in user. This ID is not meant to be presented to the user,
-but used as an opaque string to pass on to backends or use in frontend logic.
-
-TODO: The intention of the user ID is to be able to tie the user to an identity
-that is known by the catalog and/or identity backend. It should for example be
-possible to fetch all owned components using this ID.
-
-
-getUserId(): string
-
-
-### getProfile()
-
-The profile of the signed in user.
-
-
-getProfile(): ProfileInfo
-
-
-### getIdToken()
-
-An OpenID Connect ID Token which proves the identity of the signed in user.
-
-The ID token will be undefined if the signed in user does not have a verified
-identity, such as a demo user or mocked user for e2e tests.
-
-
-getIdToken(): Promise<string | undefined>
-
-
-### signOut()
-
-Sign out the current user
-
-
-signOut(): Promise<void>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### ProfileInfo
-
-Profile information of the user.
-
-
-export type ProfileInfo = {
- /**
- * Email ID.
- */
- email?: string;
-
- /**
- * Display name that can be presented to the user.
- */
- displayName?: string;
-
- /**
- * URL to an avatar image of the user.
- */
- picture?: string;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162).
-
-Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/OAuthApi.md b/docs/reference/utility-apis/OAuthApi.md
deleted file mode 100644
index 9af6b3bb53..0000000000
--- a/docs/reference/utility-apis/OAuthApi.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# OAuthApi
-
-The OAuthApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L67).
-
-The following Utility APIs implement this type:
-
-- [githubAuthApiRef](./README.md#githubauth)
-
-- [gitlabAuthApiRef](./README.md#gitlabauth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oidcAuthApiRef](./README.md#oidcauth)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-- [oneloginAuthApiRef](./README.md#oneloginauth)
-
-## Members
-
-### getAccessToken()
-
-Requests an OAuth 2 Access Token, optionally with a set of scopes. The access
-token allows you to make requests on behalf of the user, and the copes may grant
-you broader access, depending on the auth provider.
-
-Each auth provider has separate handling of scope, so you need to look at the
-documentation for each one to know what scope you need to request.
-
-This method is cheap and should be called each time an access token is used. Do
-not for example store the access token in React component state, as that could
-cause the token to expire. Instead fetch a new access token for each request.
-
-Be sure to include all required scopes when requesting an access token. When
-testing your implementation it is best to log out the Backstage session and then
-visit your plugin page directly, as you might already have some required scopes
-in your existing session. Not requesting the correct scopes can lead to 403 or
-other authorization errors, which can be tricky to debug.
-
-If the user has not yet granted access to the provider and the set of requested
-scopes, the user will be prompted to log in. The returned promise will not
-resolve until the user has successfully logged in. The returned promise can be
-rejected, but only if the user rejects the login request.
-
-
-getAccessToken(
- scope?: OAuthScope,
- options?: AuthRequestOptions,
- ): Promise<string>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AuthRequestOptions
-
-
-export type AuthRequestOptions = {
- /**
- * If this is set to true, the user will not be prompted to log in,
- * and an empty response will be returned if there is no existing session.
- *
- * This can be used to perform a check whether the user is logged in, or if you don't
- * want to force a user to be logged in, but provide functionality if they already are.
- *
- * @default false
- */
- optional?: boolean;
-
- /**
- * If this is set to true, the request will bypass the regular oauth login modal
- * and open the login popup directly.
- *
- * The method must be called synchronously from a user action for this to work in all browsers.
- *
- * @default false
- */
- instantPopup?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
-
-Referenced by: [getAccessToken](#getaccesstoken).
-
-### OAuthScope
-
-This file contains declarations for common interfaces of auth-related APIs. The
-declarations should be used to signal which type of authentication and
-authorization methods each separate auth provider supports.
-
-For example, a Google OAuth provider that supports OAuth 2 and OpenID Connect,
-would be declared as follows:
-
-const googleAuthApiRef = createApiRef({ ... })
-
-An array of scopes, or a scope string formatted according to the auth provider,
-which is typically a space separated list.
-
-See the documentation for each auth provider for the list of scopes supported by
-each provider.
-
-
-export type OAuthScope = string | string[]
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L38).
-
-Referenced by: [getAccessToken](#getaccesstoken).
diff --git a/docs/reference/utility-apis/OAuthRequestApi.md b/docs/reference/utility-apis/OAuthRequestApi.md
deleted file mode 100644
index 5f521cf288..0000000000
--- a/docs/reference/utility-apis/OAuthRequestApi.md
+++ /dev/null
@@ -1,233 +0,0 @@
-# OAuthRequestApi
-
-The OAuthRequestApi type is defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99).
-
-The following Utility API implements this type:
-[oauthRequestApiRef](./README.md#oauthrequest)
-
-## Members
-
-### createAuthRequester()
-
-A utility for showing login popups or similar things, and merging together
-multiple requests for different scopes into one request that includes all
-scopes.
-
-The passed in options provide information about the login provider, and how to
-handle auth requests.
-
-The returned AuthRequester function is used to request login with new scopes.
-These requests are merged together and forwarded to the auth handler, as soon as
-a consumer of auth requests triggers an auth flow.
-
-See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info.
-
-
-createAuthRequester<AuthResponse>(
- options: AuthRequesterOptions<AuthResponse>,
- ): AuthRequester<AuthResponse>
-
-
-### authRequest\$()
-
-Observers pending auth requests. The returned observable will emit all current
-active auth request, at most one for each created auth requester.
-
-Each request has its own info about the login provider, forwarded from the auth
-requester options.
-
-Depending on user interaction, the request should either be rejected, or used to
-trigger the auth handler. If the request is rejected, all pending AuthRequester
-calls will fail with a "RejectedError". If a auth is triggered, and the auth
-handler resolves successfully, then all currently pending AuthRequester calls
-will resolve to the value returned by the onAuthRequest call.
-
-
-authRequest$(): Observable<PendingAuthRequest[]>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AuthProvider
-
-Information about the auth provider that we're requesting a login towards.
-
-This should be shown to the user so that they can be informed about what login
-is being requested before a popup is shown.
-
-
-export type AuthProvider = {
- /**
- * Title for the auth provider, for example "GitHub"
- */
- title: string;
-
- /**
- * Icon for the auth provider.
- */
- icon: IconComponent;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27).
-
-Referenced by: [AuthRequesterOptions](#authrequesteroptions),
-[PendingAuthRequest](#pendingauthrequest).
-
-### AuthRequester
-
-Function used to trigger new auth requests for a set of scopes.
-
-The returned promise will resolve to the same value returned by the
-onAuthRequest in the AuthRequesterOptions. Or rejected, if the request is
-rejected.
-
-This function can be called multiple times before the promise resolves. All
-calls will be merged into one request, and the scopes forwarded to the
-onAuthRequest will be the union of all requested scopes.
-
-
-export type AuthRequester<AuthResponse> = (
- scopes: Set<string>,
-) => Promise<AuthResponse>
-
-
-Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66).
-
-Referenced by: [createAuthRequester](#createauthrequester).
-
-### AuthRequesterOptions
-
-Describes how to handle auth requests. Both how to show them to the user, and
-what to do when the user accesses the auth request.
-
-
-export type AuthRequesterOptions<AuthResponse> = {
- /**
- * Information about the auth provider, which will be forwarded to auth requests.
- */
- provider: AuthProvider;
-
- /**
- * Implementation of the auth flow, which will be called synchronously when
- * trigger() is called on an auth requests.
- */
- onAuthRequest(scopes: Set<string>): Promise<AuthResponse>;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43).
-
-Referenced by: [createAuthRequester](#createauthrequester).
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [authRequest\$](#authrequest).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### PendingAuthRequest
-
-An pending auth request for a single auth provider. The request will remain in
-this pending state until either reject() or trigger() is called.
-
-Any new requests for the same provider are merged into the existing pending
-request, meaning there will only ever be a single pending request for a given
-provider.
-
-
-export type PendingAuthRequest = {
- /**
- * Information about the auth provider, as given in the AuthRequesterOptions
- */
- provider: AuthProvider;
-
- /**
- * Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
- */
- reject: () => void;
-
- /**
- * Trigger the auth request to continue the auth flow, by for example showing a popup.
- *
- * Synchronously calls onAuthRequest with all scope currently in the request.
- */
- trigger(): Promise<void>;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77).
-
-Referenced by: [authRequest\$](#authrequest).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/OpenIdConnectApi.md b/docs/reference/utility-apis/OpenIdConnectApi.md
deleted file mode 100644
index 6d05af6189..0000000000
--- a/docs/reference/utility-apis/OpenIdConnectApi.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# OpenIdConnectApi
-
-The OpenIdConnectApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L99).
-
-The following Utility APIs implement this type:
-
-- [auth0AuthApiRef](./README.md#auth0auth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oidcAuthApiRef](./README.md#oidcauth)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-- [oneloginAuthApiRef](./README.md#oneloginauth)
-
-## Members
-
-### getIdToken()
-
-Requests an OpenID Connect ID Token.
-
-This method is cheap and should be called each time an ID token is used. Do not
-for example store the id token in React component state, as that could cause the
-token to expire. Instead fetch a new id token for each request.
-
-If the user has not yet logged in to Google inside Backstage, the user will be
-prompted to log in. The returned promise will not resolve until the user has
-successfully logged in. The returned promise can be rejected, but only if the
-user rejects the login request.
-
-
-getIdToken(options?: AuthRequestOptions): Promise<string>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AuthRequestOptions
-
-
-export type AuthRequestOptions = {
- /**
- * If this is set to true, the user will not be prompted to log in,
- * and an empty response will be returned if there is no existing session.
- *
- * This can be used to perform a check whether the user is logged in, or if you don't
- * want to force a user to be logged in, but provide functionality if they already are.
- *
- * @default false
- */
- optional?: boolean;
-
- /**
- * If this is set to true, the request will bypass the regular oauth login modal
- * and open the login popup directly.
- *
- * The method must be called synchronously from a user action for this to work in all browsers.
- *
- * @default false
- */
- instantPopup?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
-
-Referenced by: [getIdToken](#getidtoken).
diff --git a/docs/reference/utility-apis/ProfileInfoApi.md b/docs/reference/utility-apis/ProfileInfoApi.md
deleted file mode 100644
index 1a2f94d031..0000000000
--- a/docs/reference/utility-apis/ProfileInfoApi.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# ProfileInfoApi
-
-The ProfileInfoApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L117).
-
-The following Utility APIs implement this type:
-
-- [auth0AuthApiRef](./README.md#auth0auth)
-
-- [githubAuthApiRef](./README.md#githubauth)
-
-- [gitlabAuthApiRef](./README.md#gitlabauth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oidcAuthApiRef](./README.md#oidcauth)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-- [oneloginAuthApiRef](./README.md#oneloginauth)
-
-- [samlAuthApiRef](./README.md#samlauth)
-
-## Members
-
-### getProfile()
-
-Get profile information for the user as supplied by this auth provider.
-
-If the optional flag is not set, a session is guaranteed to be returned, while
-if the optional flag is set, the session may be undefined. See
-@AuthRequestOptions for more details.
-
-
-getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### AuthRequestOptions
-
-
-export type AuthRequestOptions = {
- /**
- * If this is set to true, the user will not be prompted to log in,
- * and an empty response will be returned if there is no existing session.
- *
- * This can be used to perform a check whether the user is logged in, or if you don't
- * want to force a user to be logged in, but provide functionality if they already are.
- *
- * @default false
- */
- optional?: boolean;
-
- /**
- * If this is set to true, the request will bypass the regular oauth login modal
- * and open the login popup directly.
- *
- * The method must be called synchronously from a user action for this to work in all browsers.
- *
- * @default false
- */
- instantPopup?: boolean;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
-
-Referenced by: [getProfile](#getprofile).
-
-### ProfileInfo
-
-Profile information of the user.
-
-
-export type ProfileInfo = {
- /**
- * Email ID.
- */
- email?: string;
-
- /**
- * Display name that can be presented to the user.
- */
- displayName?: string;
-
- /**
- * URL to an avatar image of the user.
- */
- picture?: string;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162).
-
-Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md
deleted file mode 100644
index aefbb4b925..0000000000
--- a/docs/reference/utility-apis/README.md
+++ /dev/null
@@ -1,202 +0,0 @@
-# Backstage Core Utility APIs
-
-The following is a list of all Utility APIs defined by `@backstage/core`. They
-are available to use by plugins and components, and can be accessed using the
-`useApi` hook, also provided by `@backstage/core`. For more information, see
-https://github.com/backstage/backstage/blob/master/docs/api/utility-apis.md.
-
-### alert
-
-Used to report alerts and forward them to the app
-
-Implemented type: [AlertApi](./AlertApi.md)
-
-ApiRef:
-[alertApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L41)
-
-### appTheme
-
-API Used to configure the app theme, and enumerate options
-
-Implemented type: [AppThemeApi](./AppThemeApi.md)
-
-ApiRef:
-[appThemeApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L80)
-
-### auth0Auth
-
-Provides authentication towards Auth0 APIs
-
-Implemented types: [OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[auth0AuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L275)
-
-### config
-
-Used to access runtime configuration
-
-Implemented type: [Config](./Config.md)
-
-ApiRef:
-[configApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ConfigApi.ts#L25)
-
-### discovery
-
-Provides service discovery of backend plugins
-
-Implemented type: [DiscoveryApi](./DiscoveryApi.md)
-
-ApiRef:
-[discoveryApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44)
-
-### error
-
-Used to report errors and forward them to the app
-
-Implemented type: [ErrorApi](./ErrorApi.md)
-
-ApiRef:
-[errorApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L65)
-
-### featureFlags
-
-Used to toggle functionality in features across Backstage
-
-Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md)
-
-ApiRef:
-[featureFlagsApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L83)
-
-### githubAuth
-
-Provides authentication towards GitHub APIs
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[githubAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L232)
-
-### gitlabAuth
-
-Provides authentication towards GitLab APIs
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[gitlabAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L262)
-
-### googleAuth
-
-Provides authentication towards Google APIs and identities
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[googleAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L215)
-
-### identity
-
-Provides access to the identity of the signed in user
-
-Implemented type: [IdentityApi](./IdentityApi.md)
-
-ApiRef:
-[identityApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L53)
-
-### microsoftAuth
-
-Provides authentication towards Microsoft APIs and identities
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[microsoftAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L289)
-
-### oauth2
-
-Example of how to use oauth2 custom provider
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[oauth2ApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L303)
-
-### oauthRequest
-
-An API for implementing unified OAuth flows in Backstage
-
-Implemented type: [OAuthRequestApi](./OAuthRequestApi.md)
-
-ApiRef:
-[oauthRequestApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130)
-
-### oidcAuth
-
-Example of how to use oidc custom provider
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[oidcAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L317)
-
-### oktaAuth
-
-Provides authentication towards Okta APIs
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[oktaAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L245)
-
-### oneloginAuth
-
-Provides authentication towards OneLogin APIs and identities
-
-Implemented types: [OAuthApi](./OAuthApi.md),
-[OpenIdConnectApi](./OpenIdConnectApi.md),
-[ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[oneloginAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L338)
-
-### samlAuth
-
-Example of how to use SAML custom provider
-
-Implemented types: [ProfileInfoApi](./ProfileInfoApi.md),
-[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
-
-ApiRef:
-[samlAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L331)
-
-### storage
-
-Provides the ability to store data which is unique to the user
-
-Implemented type: [StorageApi](./StorageApi.md)
-
-ApiRef:
-[storageApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L68)
diff --git a/docs/reference/utility-apis/SessionApi.md b/docs/reference/utility-apis/SessionApi.md
deleted file mode 100644
index 4b584d92c8..0000000000
--- a/docs/reference/utility-apis/SessionApi.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# SessionApi
-
-The SessionApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L190).
-
-The following Utility APIs implement this type:
-
-- [auth0AuthApiRef](./README.md#auth0auth)
-
-- [githubAuthApiRef](./README.md#githubauth)
-
-- [gitlabAuthApiRef](./README.md#gitlabauth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oidcAuthApiRef](./README.md#oidcauth)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-- [oneloginAuthApiRef](./README.md#oneloginauth)
-
-- [samlAuthApiRef](./README.md#samlauth)
-
-## Members
-
-### signIn()
-
-Sign in with a minimum set of permissions.
-
-
-signIn(): Promise<void>
-
-
-### signOut()
-
-Sign out from the current session. This will reload the page.
-
-
-signOut(): Promise<void>
-
-
-### sessionState\$()
-
-Observe the current state of the auth session. Emits the current state on
-subscription.
-
-
-sessionState$(): Observable<SessionState>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [sessionState\$](#sessionstate).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### SessionState
-
-Session state values passed to subscribers of the SessionApi.
-
-
-export enum SessionState {
- SignedIn = 'SignedIn',
- SignedOut = 'SignedOut',
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L182).
-
-Referenced by: [sessionState\$](#sessionstate).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/SessionStateApi.md b/docs/reference/utility-apis/SessionStateApi.md
deleted file mode 100644
index a8a4c3bc3d..0000000000
--- a/docs/reference/utility-apis/SessionStateApi.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# SessionStateApi
-
-The SessionStateApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201).
-
-The following Utility APIs implement this type:
-
-- [auth0AuthApiRef](./README.md#auth0auth)
-
-- [githubAuthApiRef](./README.md#githubauth)
-
-- [gitlabAuthApiRef](./README.md#gitlabauth)
-
-- [googleAuthApiRef](./README.md#googleauth)
-
-- [microsoftAuthApiRef](./README.md#microsoftauth)
-
-- [oauth2ApiRef](./README.md#oauth2)
-
-- [oktaAuthApiRef](./README.md#oktaauth)
-
-## Members
-
-### sessionState\$()
-
-
-sessionState$(): Observable<SessionState>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53).
-
-Referenced by: [sessionState\$](#sessionstate).
-
-### Observer
-
-This file contains non-react related core types used through Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### SessionState
-
-Session state values passed to subscribers of the SessionStateApi.
-
-
-export enum SessionState {
- SignedIn = 'SignedIn',
- SignedOut = 'SignedOut',
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192).
-
-Referenced by: [sessionState\$](#sessionstate).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/StorageApi.md b/docs/reference/utility-apis/StorageApi.md
deleted file mode 100644
index 3247d28f60..0000000000
--- a/docs/reference/utility-apis/StorageApi.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# StorageApi
-
-The StorageApi type is defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
-
-The following Utility API implements this type:
-[storageApiRef](./README.md#storage)
-
-## Members
-
-### forBucket()
-
-Create a bucket to store data in.
-
-
-forBucket(name: string): StorageApi
-
-
-### get()
-
-Get the current value for persistent data, use observe\$ to be notified of
-updates.
-
-
-get<T>(key: string): T | undefined
-
-
-### remove()
-
-Remove persistent data.
-
-
-remove(key: string): Promise<void>
-
-
-### set()
-
-Save persistent data, and emit messages to anyone that is using observe\$ for
-this key
-
-
-set(key: string, data: any): Promise<void>
-
-
-### observe\$()
-
-Observe changes on a particular key in the bucket
-
-
-observe$<T>(key: string): Observable<StorageValueChange<T>>
-
-
-## Supporting types
-
-These types are part of the API declaration, but may not be unique to this API.
-
-### Observable
-
-Observable sequence of values and errors, see TC39.
-
-https://github.com/tc39/proposal-observable
-
-This is used as a common return type for observable values and can be created
-using many different observable implementations, such as zen-observable or
-RxJS 5.
-
-
-export type Observable<T> = {
- /**
- * Subscribes to this observable to start receiving new values.
- */
- subscribe(observer: Observer<T>): Subscription;
- subscribe(
- onNext: (value: T) => void,
- onError?: (error: Error) => void,
- onComplete?: () => void,
- ): Subscription;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
-
-Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
-
-### Observer
-
-This file contains non-react related core types used throughout Backstage.
-
-Observer interface for consuming an Observer, see TC39.
-
-
-export type Observer<T> = {
- next?(value: T): void;
- error?(error: Error): void;
- complete?(): void;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
-
-Referenced by: [Observable](#observable).
-
-### StorageApi
-
-
-export interface StorageApi {
- /**
- * Create a bucket to store data in.
- * @param {String} name Namespace for the storage to be stored under,
- * will inherit previous namespaces too
- */
- forBucket(name: string): StorageApi;
-
- /**
- * Get the current value for persistent data, use observe$ to be notified of updates.
- *
- * @param {String} key Unique key associated with the data.
- * @return {Object} data The data that should is stored.
- */
- get<T>(key: string): T | undefined;
-
- /**
- * Remove persistent data.
- *
- * @param {String} key Unique key associated with the data.
- */
- remove(key: string): Promise<void>;
-
- /**
- * Save persistent data, and emit messages to anyone that is using observe$ for this key
- *
- * @param {String} key Unique key associated with the data.
- */
- set(key: string, data: any): Promise<void>;
-
- /**
- * Observe changes on a particular key in the bucket
- * @param {String} key Unique key associated with the data
- */
- observe$<T>(key: string): Observable<StorageValueChange<T>>;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
-
-Referenced by: [forBucket](#forbucket).
-
-### StorageValueChange
-
-
-export type StorageValueChange<T = any> = {
- key: string;
- newValue?: T;
-}
-
-
-Defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L21).
-
-Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
-
-### Subscription
-
-Subscription returned when subscribing to an Observable, see TC39.
-
-
-export type Subscription = {
- /**
- * Cancels the subscription
- */
- unsubscribe(): void;
-
- /**
- * Value indicating whether the subscription is closed.
- */
- readonly closed: Boolean;
-}
-
-
-Defined at
-[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
-
-Referenced by: [Observable](#observable).
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index d200b615f1..dc8aa516cf 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -234,21 +234,11 @@
"dls/contributing-to-storybook",
"dls/figma"
],
- "API references": [
+ "API Reference": [
{
"type": "subcategory",
- "label": "TypeScript API",
- "ids": [
- "api/utility-apis",
- "reference/utility-apis/README",
- "reference/createPlugin",
- "reference/createPlugin-feature-flags"
- ]
- },
- {
- "type": "subcategory",
- "label": "Backend APIs",
- "ids": ["api/backend"]
+ "label": "Guides",
+ "ids": [ "api/utility-apis" ]
}
],
"Tutorials": [