Documentation Index
Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
Use this file to discover all available pages before exploring further.
Authentication and host communication APIs for Flows applications running in CDF.
Use these APIs when building Flows 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({ 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 }));
