Flows Auth API

Connect your Flows custom app to the Cognite Data Fusion (CDF) host window and get credentials for authenticated SDK access. Call connectToHostApp once at app startup. It returns a HostAppAPI instance with methods to get the current project, base URL, and access token. Use those credentials to construct a CogniteClient. For navigation, state, sidebar visibility, fullscreen, and agent integration, see Host App API.

Prerequisites

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

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

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()
      .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 credential methods

The HostAppAPI instance returned by connectToHostApp includes methods for the current project, base URL, and access token. For navigation, state, sidebar visibility, fullscreen, and agent integration, see Host App API.

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
}

Build

Prerequisites

connectToHostApp

Return value

Example: connect and get project

HostAppAPI credential methods

getProject

getBaseUrl

getAccessToken

Example: construct a CogniteClient

Further reading

​Prerequisites

​connectToHostApp

​Return value

​Example: connect and get project

​HostAppAPI credential methods

​getProject

​getBaseUrl

​getAccessToken

​Example: construct a CogniteClient

​Further reading

Prerequisites

connectToHostApp

Return value

Example: connect and get project

HostAppAPI credential methods

getProject

getBaseUrl

getAccessToken

Example: construct a CogniteClient

Further reading