Skip to main content
Authentication and host communication APIs for Flows applications running in CDF. Use these APIs when building Flows custom apps that need authenticated access to CDF resources. The connectToHostApp function establishes communication with the CDF host window and gives you a HostAppAPI instance to retrieve credentials and construct an authenticated Cognite SDK.

​
Prerequisites

​
connectToHostApp

Connects your app to the CDF host window and returns a HostAppAPI instance. 
import { connectToHostApp } from "@cognite/app-sdk";

const { api } = await connectToHostApp();

​
Return value

PropertyTypeDescription
apiHostAppAPIAPI for communicating with the CDF host
initialStatestring | undefinedRestored state from a previous session (if syncInternalState was used)

​
Example: connect and get project

import { useEffect, useState } from "react";
import { connectToHostApp } from "@cognite/app-sdk";

function App() {
  const [project, setProject] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | undefined>();

  useEffect(() => {
    let cancelled = false;
    connectToHostApp()
      .then(async ({ api }) => {
        if (cancelled) return;
        const proj = await api.getProject();
        if (!cancelled) setProject(proj);
      })
      .catch((err: unknown) => {
        if (cancelled) return;
        setError(err instanceof Error ? err.message : String(err));
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false);
      });
    return () => {
      cancelled = true;
    };
  }, []);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  return <div>Project: {project}</div>;
}

​
HostAppAPI

The HostAppAPI interface is returned by connectToHostApp and provides methods for interacting with the CDF host.

​
getProject

Returns the current CDF project name. 
const project = await api.getProject();

​
getBaseUrl

Returns the base URL of the CDF cluster (for example, https://greenfield.cognitedata.com). 
const baseUrl = await api.getBaseUrl();

​
getAccessToken

Returns the current access token for authenticating CDF API calls. 
const token = await api.getAccessToken();

​
Example: construct a CogniteClient

Use getProject, getBaseUrl, and getAccessToken together to build an authenticated CogniteClient from @cognite/sdk: 
import { useEffect, useState } from "react";
import { connectToHostApp } from "@cognite/app-sdk";
import { CogniteClient } from "@cognite/sdk";

function App() {
  const [sdk, setSdk] = useState<CogniteClient | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | undefined>();

  useEffect(() => {
    let cancelled = false;
    connectToHostApp()
      .then(async ({ api }) => {
        if (cancelled) return;
        const [project, baseUrl] = await Promise.all([
          api.getProject(),
          api.getBaseUrl(),
        ]);
        const client = new CogniteClient({
          project,
          baseUrl,
          getToken: () => api.getAccessToken(),
        });
        if (!cancelled) setSdk(client);
      })
      .catch((err: unknown) => {
        if (cancelled) return;
        setError(err instanceof Error ? err.message : String(err));
      })
      .finally(() => {
        if (!cancelled) setIsLoading(false);
      });
    return () => {
      cancelled = true;
    };
  }, []);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  // pass sdk down or use context
}
Navigates to a path within CDF. 
await api.navigateInternal({
  path: "/my-other-app",
  queryParams: { tab: "overview" },
});
ParameterTypeDescription
pathstringCDF-relative path to navigate to
queryParamsRecord<string, string> (optional)Query parameters
hashstring (optional)URL hash fragment
Opens an external URL. 
await api.navigateExternal({
  url: "https://docs.cognite.com",
  openInNewTab: true,
});
ParameterTypeDescription
urlstringHTTPS URL to navigate to
openInNewTabboolean (optional)Open in a new browser tab

​
syncInternalState

Saves a serialized state string to the customAppInternalState URL search param. The saved state is passed back as initialState the next time the app mounts. Users can return to the same view after navigating away or refreshing. Because the state lives in the URL, the link is shareable. 
const handled = await api.syncInternalState(
  JSON.stringify({ view: "dashboard", assetId: "12345" })
);
ParameterTypeRequiredDescription
statestringYesJSON-serialized state. Must be a string. Call JSON.stringify before passing.
ReturnsPromise<boolean>. true if the host saved the state; false if the host did not handle the call (for example, in standalone dev mode).
See App state in URLs for a full guide covering state restoration, what to include in persisted state, and a complete example.
Last modified on June 24, 2026