Skip to main content
Use a project service key for SDK requests and OpenTelemetry exports. Create it in Settings → Integrations & API keys within the project you want to use.

​
Configure the application

Store the key as HUE_API_KEY in your server environment or secret manager. Pass it to the SDK constructor, as shown in the quickstart. Hue constructors do not automatically load environment files. For direct HTTP requests, authentication uses Authorization: Bearer <project-service-key>. The key determines the destination project. Resource attributes, observed user IDs and session IDs cannot select a different project.

​
Understand access

Current service keys have the project_write capability. They authorize telemetry ingestion and project evaluation API operations; telemetry-only and read-only service keys are not currently available. Treat the key as a project credential and keep it out of browser bundles, logs, source control and prompts. A service key does not represent a signed-in Hue user. Human review and general trace browsing use the application’s authenticated user session. The SDKs do not currently expose a general trace-search API.

​
Verify and rotate

Call hue.checkConnection() in TypeScript or hue.validate_project() in Python. These send a project lookup without a trace and return the project identity. Confirm it matches the project you intend to use before exporting data. When replacing a key, configure the replacement in the server’s secret store, verify the connection, then revoke the old key in project settings. Never include either credential in a support report. A successful connection check validates project access; the first-trace check separately verifies instrumentation and delivery.

​
Connection settings

Both SDKs default to https://app.hue.run. Omit baseUrl in TypeScript and base_url in Python for Hue Cloud. You do not need to choose or discover a different endpoint for a normal Hue Cloud integration. For local development or another configured Hue deployment, pass a different origin through baseUrl in TypeScript or base_url in Python. If your application uses HUE_BASE_URL, read it explicitly and pass it to the constructor. SDKs do not load environment files automatically. Supply an origin without credentials, an API path, query parameters or a fragment. HTTPS is required except for loopback HTTP. SDKs append their own paths; a standard OTLP exporter instead needs the full signal endpoint.