diff --git a/docs/reference/utility-apis/AlertApi.md b/docs/reference/utility-apis/AlertApi.md
new file mode 100644
index 0000000000..b7d1a4d65d
--- /dev/null
+++ b/docs/reference/utility-apis/AlertApi.md
@@ -0,0 +1,115 @@
+# AlertApi
+
+The AlertApi type is defined at
+[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/AlertApi.ts#L29).
+
+The following Utility API implements this type:
+[alertApiRef](./README.md#alertapiref)
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [alert\$](#alert-).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..79d41ef6f6
--- /dev/null
+++ b/docs/reference/utility-apis/AppThemeApi.md
@@ -0,0 +1,225 @@
+# AppThemeApi
+
+The AppThemeApi type is defined at
+[packages/core-api/src/apis/definitions/AppThemeApi.ts:50](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/AppThemeApi.ts#L50).
+
+The following Utility API implements this type:
+[appThemeApiRef](./README.md#appthemeapiref)
+
+## 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;
+}
+
+
+Defined at
+[packages/core-api/src/apis/definitions/AppThemeApi.ts:24](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/AppThemeApi.ts#L24).
+
+Referenced by: [getInstalledThemes](#getinstalledthemes).
+
+### BackstagePalette
+
+
+export type BackstagePalette = Palette & PaletteAdditions
+
+
+Defined at
+[packages/theme/src/types.ts:63](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/theme/src/types.ts#L63).
+
+Referenced by: [BackstageTheme](#backstagetheme).
+
+### BackstageTheme
+
+
+export interface BackstageTheme extends Theme {
+ palette: BackstagePalette;
+}
+
+
+Defined at
+[packages/theme/src/types.ts:66](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/theme/src/types.ts#L66).
+
+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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [activeThemeId\$](#activethemeid-).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L24).
+
+Referenced by: [Observable](#observable).
+
+### 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;
+ sidebar: string;
+ tabbar: {
+ indicator: string;
+ };
+ bursts: {
+ fontColor: string;
+ slackChannelText: string;
+ backgroundColor: {
+ default: string;
+ };
+ };
+ pinSidebarButton: {
+ icon: string;
+ background: string;
+ };
+}
+
+
+Defined at
+[packages/theme/src/types.ts:23](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..717a294621
--- /dev/null
+++ b/docs/reference/utility-apis/BackstageIdentityApi.md
@@ -0,0 +1,88 @@
+# BackstageIdentityApi
+
+The BackstageIdentityApi type is defined at
+[packages/core-api/src/apis/definitions/auth.ts:144](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L144).
+
+The following Utility APIs implement this type:
+
+- [githubAuthApiRef](./README.md#githubauthapiref)
+
+- [gitlabAuthApiRef](./README.md#gitlabauthapiref)
+
+- [googleAuthApiRef](./README.md#googleauthapiref)
+
+- [oktaAuthApiRef](./README.md#oktaauthapiref)
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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:157](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L157).
+
+Referenced by: [getBackstageIdentity](#getbackstageidentity).
diff --git a/docs/reference/utility-apis/Config.md b/docs/reference/utility-apis/Config.md
new file mode 100644
index 0000000000..ef53c5adcf
--- /dev/null
+++ b/docs/reference/utility-apis/Config.md
@@ -0,0 +1,179 @@
+# Config
+
+The Config type is defined at
+[packages/config/src/types.ts:32](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/config/src/types.ts#L32).
+
+The following Utility API implements this type:
+[configApiRef](./README.md#configapiref)
+
+## Members
+
+### 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 = {
+ 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/ErrorApi.md b/docs/reference/utility-apis/ErrorApi.md
new file mode 100644
index 0000000000..efd4a3ed00
--- /dev/null
+++ b/docs/reference/utility-apis/ErrorApi.md
@@ -0,0 +1,135 @@
+# ErrorApi
+
+The ErrorApi type is defined at
+[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/ErrorApi.ts#L53).
+
+The following Utility API implements this type:
+[errorApiRef](./README.md#errorapiref)
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [error\$](#error-).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..b3320b404a
--- /dev/null
+++ b/docs/reference/utility-apis/FeatureFlagsApi.md
@@ -0,0 +1,33 @@
+# FeatureFlagsApi
+
+The FeatureFlagsApi type is defined at
+[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:41](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L41).
+
+The following Utility API implements this type:
+[featureFlagsApiRef](./README.md#featureflagsapiref)
+
+## Members
+
+### registeredFeatureFlags
+
+Store a list of registered feature flags.
+
+
+registeredFeatureFlags: FeatureFlagsRegistryItem[]
+
+
+### getFlags()
+
+Get a list of all feature flags from the current user.
+
+
+getFlags(): UserFlags
+
+
+### getRegisteredFlags()
+
+Get a list of all registered flags.
+
+
+getRegisteredFlags(): FeatureFlagsRegistry
+
diff --git a/docs/reference/utility-apis/IdentityApi.md b/docs/reference/utility-apis/IdentityApi.md
new file mode 100644
index 0000000000..f5de414cf5
--- /dev/null
+++ b/docs/reference/utility-apis/IdentityApi.md
@@ -0,0 +1,81 @@
+# IdentityApi
+
+The IdentityApi type is defined at
+[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/IdentityApi.ts#L22).
+
+The following Utility API implements this type:
+[identityApiRef](./README.md#identityapiref)
+
+## 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>
+
+
+### logout()
+
+Log out the current user
+
+
+logout(): 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:172](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L172).
+
+Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/OAuthApi.md b/docs/reference/utility-apis/OAuthApi.md
new file mode 100644
index 0000000000..e3334601f1
--- /dev/null
+++ b/docs/reference/utility-apis/OAuthApi.md
@@ -0,0 +1,119 @@
+# OAuthApi
+
+The OAuthApi type is defined at
+[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L67).
+
+The following Utility APIs implement this type:
+
+- [githubAuthApiRef](./README.md#githubauthapiref)
+
+- [gitlabAuthApiRef](./README.md#gitlabauthapiref)
+
+- [googleAuthApiRef](./README.md#googleauthapiref)
+
+- [oauth2ApiRef](./README.md#oauth2apiref)
+
+- [oktaAuthApiRef](./README.md#oktaauthapiref)
+
+## 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>
+
+
+### logout()
+
+Log out the user's session. This will reload the page.
+
+
+logout(): Promise<void>
+
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..895c515fb0
--- /dev/null
+++ b/docs/reference/utility-apis/OAuthRequestApi.md
@@ -0,0 +1,232 @@
+# OAuthRequestApi
+
+The OAuthRequestApi type is defined at
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99).
+
+The following Utility API implements this type:
+[oauthRequestApiRef](./README.md#oauthrequestapiref)
+
+## Members
+
+### createAuthRequester()
+
+A utility for showing login popups or similar things, and merging together
+multiple requests for different scopes into one request that inclues 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 panding 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [authRequest\$](#authrequest-).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..c626ccf3a1
--- /dev/null
+++ b/docs/reference/utility-apis/OpenIdConnectApi.md
@@ -0,0 +1,75 @@
+# OpenIdConnectApi
+
+The OpenIdConnectApi type is defined at
+[packages/core-api/src/apis/definitions/auth.ts:104](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L104).
+
+The following Utility APIs implement this type:
+
+- [googleAuthApiRef](./README.md#googleauthapiref)
+
+- [oauth2ApiRef](./README.md#oauth2apiref)
+
+- [oktaAuthApiRef](./README.md#oktaauthapiref)
+
+## 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>
+
+
+### logout()
+
+Log out the user's session. This will reload the page.
+
+
+logout(): Promise<void>
+
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..6fcbc99950
--- /dev/null
+++ b/docs/reference/utility-apis/ProfileInfoApi.md
@@ -0,0 +1,94 @@
+# ProfileInfoApi
+
+The ProfileInfoApi type is defined at
+[packages/core-api/src/apis/definitions/auth.ts:127](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L127).
+
+The following Utility APIs implement this type:
+
+- [githubAuthApiRef](./README.md#githubauthapiref)
+
+- [gitlabAuthApiRef](./README.md#gitlabauthapiref)
+
+- [googleAuthApiRef](./README.md#googleauthapiref)
+
+- [oauth2ApiRef](./README.md#oauth2apiref)
+
+- [oktaAuthApiRef](./README.md#oktaauthapiref)
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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:172](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L172).
+
+Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md
new file mode 100644
index 0000000000..398d55f605
--- /dev/null
+++ b/docs/reference/utility-apis/README.md
@@ -0,0 +1,135 @@
+# 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/spotify/backstage/blob/master/docs/api/utility-apis.md.
+
+### alert
+
+Used to report alerts and forward them to the app
+
+Implemented type: [AlertApi](./AlertApi)
+
+ApiRef:
+[alertApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/AlertApi.ts#L41)
+
+### appTheme
+
+API Used to configure the app theme, and enumerate options
+
+Implemented type: [AppThemeApi](./AppThemeApi)
+
+ApiRef:
+[appThemeApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/AppThemeApi.ts#L74)
+
+### config
+
+Used to access runtime configuration
+
+Implemented type: [Config](./Config)
+
+ApiRef:
+[configApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/ConfigApi.ts#L22)
+
+### error
+
+Used to report errors and forward them to the app
+
+Implemented type: [ErrorApi](./ErrorApi)
+
+ApiRef:
+[errorApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/ErrorApi.ts#L65)
+
+### featureFlags
+
+Used to toggle functionality in features across Backstage
+
+Implemented type: [FeatureFlagsApi](./FeatureFlagsApi)
+
+ApiRef:
+[featureFlagsApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L58)
+
+### githubAuth
+
+Provides authentication towards Github APIs
+
+Implemented types: [OAuthApi](./OAuthApi), [ProfileInfoApi](./ProfileInfoApi),
+[BackstageIdentityApi](./BackstageIdentityApi),
+[SessionStateApi](./SessionStateApi)
+
+ApiRef:
+[githubAuthApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L230)
+
+### gitlabAuth
+
+Provides authentication towards Gitlab APIs
+
+Implemented types: [OAuthApi](./OAuthApi), [ProfileInfoApi](./ProfileInfoApi),
+[BackstageIdentityApi](./BackstageIdentityApi),
+[SessionStateApi](./SessionStateApi)
+
+ApiRef:
+[gitlabAuthApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L260)
+
+### googleAuth
+
+Provides authentication towards Google APIs and identities
+
+Implemented types: [OAuthApi](./OAuthApi),
+[OpenIdConnectApi](./OpenIdConnectApi), [ProfileInfoApi](./ProfileInfoApi),
+[BackstageIdentityApi](./BackstageIdentityApi),
+[SessionStateApi](./SessionStateApi)
+
+ApiRef:
+[googleAuthApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L213)
+
+### identity
+
+Provides access to the identity of the signed in user
+
+Implemented type: [IdentityApi](./IdentityApi)
+
+ApiRef:
+[identityApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/IdentityApi.ts#L54)
+
+### oauth2
+
+Example of how to use oauth2 custom provider
+
+Implemented types: [OAuthApi](./OAuthApi),
+[OpenIdConnectApi](./OpenIdConnectApi), [ProfileInfoApi](./ProfileInfoApi),
+[SessionStateApi](./SessionStateApi)
+
+ApiRef:
+[oauth2ApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L270)
+
+### oauthRequest
+
+An API for implementing unified OAuth flows in Backstage
+
+Implemented type: [OAuthRequestApi](./OAuthRequestApi)
+
+ApiRef:
+[oauthRequestApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130)
+
+### oktaAuth
+
+Provides authentication towards Okta APIs
+
+Implemented types: [OAuthApi](./OAuthApi),
+[OpenIdConnectApi](./OpenIdConnectApi), [ProfileInfoApi](./ProfileInfoApi),
+[BackstageIdentityApi](./BackstageIdentityApi),
+[SessionStateApi](./SessionStateApi)
+
+ApiRef:
+[oktaAuthApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L243)
+
+### storage
+
+Provides the ability to store data which is unique to the user
+
+Implemented type: [StorageApi](./StorageApi)
+
+ApiRef:
+[storageApiRef](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/StorageApi.ts#L68)
diff --git a/docs/reference/utility-apis/SessionStateApi.md b/docs/reference/utility-apis/SessionStateApi.md
new file mode 100644
index 0000000000..d15074aa9d
--- /dev/null
+++ b/docs/reference/utility-apis/SessionStateApi.md
@@ -0,0 +1,115 @@
+# SessionStateApi
+
+The SessionStateApi type is defined at
+[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/auth.ts#L201).
+
+The following Utility APIs implement this type:
+
+- [githubAuthApiRef](./README.md#githubauthapiref)
+
+- [gitlabAuthApiRef](./README.md#gitlabauthapiref)
+
+- [googleAuthApiRef](./README.md#googleauthapiref)
+
+- [oauth2ApiRef](./README.md#oauth2apiref)
+
+- [oktaAuthApiRef](./README.md#oktaauthapiref)
+
+## 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [sessionState\$](#sessionstate-).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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
new file mode 100644
index 0000000000..dd366bcf18
--- /dev/null
+++ b/docs/reference/utility-apis/StorageApi.md
@@ -0,0 +1,186 @@
+# StorageApi
+
+The StorageApi type is defined at
+[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
+
+The following Utility API implements this type:
+[storageApiRef](./README.md#storageapiref)
+
+## 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 persistant 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L53).
+
+Referenced by: [observe\$](#observe-), [StorageApi](#storageapi).
+
+### Observer
+
+This file contains non-react related core types used throught 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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 persistant 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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/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/spotify/backstage/blob/4df02a253f6903e1ca20184369f5655e2d49d893/packages/core-api/src/types.ts#L33).
+
+Referenced by: [Observable](#observable).