Flows Auth API - Cognite Docs

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

A Flows app created with npx @cognite/cli@latest apps create
Basic understanding of React hooks and useEffect

Get started with Cognite Flows — Create your first app
Run your app locally — Development with authentication
Flows features — TanStack Query integration with connectToHostApp

connectToHostApp

Connects your app to the CDF host window and returns a HostAppAPI instance.

import { connectToHostApp } from "@cognite/app-sdk";

const { api } = await connectToHostApp({ applicationName: "my-app" });

Parameters

The argument is optional. When provided, it is used for identification in the host.

Parameter	Type	Description
`applicationName`	`string` (optional)	The name of your application

Return value

Property	Type	Description
`api`	`HostAppAPI`	API for communicating with the CDF host
`initialState`	`string \| undefined`	Restored 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({ applicationName: "my-app" })
      .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({ applicationName: "my-app" })
      .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
}

navigateInternal

Navigates to a path within CDF.

await api.navigateInternal({
  path: "/my-other-app",
  queryParams: { tab: "overview" },
});

Parameter	Type	Description
`path`	`string`	CDF-relative path to navigate to
`queryParams`	`Record<string, string>` (optional)	Query parameters
`hash`	`string` (optional)	URL hash fragment

navigateExternal

Opens an external URL.

await api.navigateExternal({
  url: "https://docs.cognite.com",
  openInNewTab: true,
});

Parameter	Type	Description
`url`	`string`	HTTPS URL to navigate to
`openInNewTab`	`boolean` (optional)	Open in a new browser tab

syncInternalState

Synchronizes app state with CDF for bookmarking and sharing. The saved state is restored as initialState on the next session.

await api.syncInternalState(JSON.stringify({ view: "dashboard", id: 42 }));

​Prerequisites

​Related guides

​connectToHostApp

​Parameters

​Return value

​Example: connect and get project

​HostAppAPI

​getProject

​getBaseUrl

​getAccessToken

​Example: construct a CogniteClient

​navigateInternal

​navigateExternal

​syncInternalState