Authentication

Every route lives under the API URL shown in the managed application's Outputs in the Azure portal, for example https://ccapi-….azurecontainerapps.io. There is no shared Datawareness host: each install has its own.

There are three ways in, each for a different caller:

Credential	Send as	Reaches	Use it for
API key	X-API-Key: <key> header (webhooks also accept ?key=)	Trigger routes, run and load-log status, queue status, inbound webhooks, and (agent keys) the Gateway routes	Schedulers, pipelines and other systems that start loads or push webhooks. See API keys.
Cloud Connector sign-in token	Authorization: Bearer <token>	Every route except the Data API	People and tools acting as a signed-in user, for example calling the configuration routes or running an action.
Cloud Connector Data token	Authorization: Bearer <token>	The Data API (/api/data) only	Power BI, Excel and scripts reading loaded data. See Data API.

API keys never reach the Data API, and a Cloud Connector sign-in token is refused there.

Choosing the environment

On an install with several environments, the URLs are identical in every environment. What decides where a call lands:

• API key — each environment has its own key, and the key names the environment. A key and an X-CC-Environment header that disagree are refused.
• Sign-in token — add the header X-CC-Environment: <key>, for example X-CC-Environment: test. No header means the default environment.
• Data API — also accepts ?environment=<key>.

API keys

The quickest way to call the trigger routes. Copy the ready-made call from the Copy API trigger URL icon on any dataset, instance, source system, job or schedule; it includes the key of the environment you are in.

curl -X POST "https://<api host>/api/connector/jobs/run" \
  -H "X-API-Key: <environment key>" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<job id>"}'

See Triggering runs from outside for every body and how to follow the run.

Cloud Connector sign-in tokens

A sign-in token is a bearer token for the Cloud Connector app registration, with the delegated scope api://<Cloud Connector client id>/access. It carries the signed-in user's access, which in Cloud Connector is full access: everyone who can sign in can change every setting. Restrict who can get one with Assignment required on the Enterprise application; see Restrict who can sign in.

Data API tokens

Request a token for the Cloud Connector Data app registration, whose Application ID URI is the API's own address, https://<api host>. A script uses the client-credentials flow with an app registration of its own; that app's service principal must be a member of a role on the Data access page.

curl -X POST "https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token" \
  --data-urlencode "client_id=<your app's client id>" \
  --data-urlencode "client_secret=<your app's secret>" \
  --data-urlencode "scope=https://<api host>/.default" \
  --data-urlencode "grant_type=client_credentials"

curl "https://<api host>/api/data/webshop.orders?pageSize=5000" \
  -H "Authorization: Bearer <access token>"

Power BI signs in interactively with Organizational account. See Reading data through the Data API.

When a call is refused

Answer	Likely cause
401 or 403 with a sign-in token	The token was minted for the wrong client ID, or the user has no assignment on the app registration.
403 The Data API is not enabled	No Cloud Connector Data client ID under Setup → Access.
403 Cloud Connector sign-in tokens are not accepted	A Cloud Connector token was sent to the Data API. Use one for the Cloud Connector Data app.
403 Not found or access denied	No enabled Data access role in that environment covers the dataset and names the caller, or the dataset does not exist.
Refused with an API key	The route is not one an API key may call, the key was regenerated, or the key and X-CC-Environment disagree.

More in Troubleshooting.