Setting up API keys for ADA | Agile Data Engine

ADA (Agile Data Agent) requires External API keys with specific endpoint permissions to interact with ADE. Use Admin UI to create the keys.

Recommendation

Create developer-specific API keys for ADA. Use the developer's email address as the API key description. This provides traceability in Designer, where the changes will show in future releases (currently not yet) as:

user.name@company.com <api-key:abc123>

API Key Permissions

Set all listed endpoints to ALLOW. Methods required: GET and POST.

Design Environment

Base path: /external-api/api/<tenant>/<installation>/design/

Endpoint	Methods	Purpose
`metadata/v1/entities/formats/yaml`	GET, POST	Fetch and push entity YAML
`metadata/v1/entities/formats/yaml/schema`	GET	Fetch YAML JSON Schema
`metadata/v1/packages/formats/json`	GET, POST	Fetch and push config packages (schedules, templates)
`metadata/v1/graphql`	GET	Package discovery, entity metadata enrichment
`metadata/v1/search` and `metadata/v1/search/**`	GET	Search metadata and trace entity, lineage, package and workflow graphs.
`deployment/v1/commits`	GET, POST	Create ADE commits (POST), list a package's commits (GET)
`deployment/v1/commits/**`	GET	Get ADE commit statuses
`deployment/v1/promotions`	GET, POST	Promote commits to a runtime environment (POST), find promotions waiting for deployment (GET)
`deployment/v1/deployments`	GET	List the deployments of a commit
`deployment/v1/deployments/**`	GET	Get deployment status and phases
`deployment/v1/environments/**`	GET	List runtime environments and their target instances
`deployment/v1/environments/<ENVIRONMENT>/instances/**`	POST	Start the deployment of promoted commits. One line per runtime environment the key may deploy to, named exactly as in ADE
`deployment/v1/commits`	GET, POST	Create ADE commits (POST), list a package's commits (GET)
`pingpong/v1`	GET	Connectivity test
`me`	GET	Authentication to MCP Server Authentication to ADA installer.

When creating API-keys in Admin UI set appropriate authorization rules. Create separate authorization rules for POST and GET.

For example, adding POST commands for example tenant s1234567 and installation datahub:

/external-api/api/s1234567/datahub/design/metadata/v1/entities/formats/yaml
/external-api/api/s1234567/datahub/design/metadata/v1/packages/formats/json
/external-api/api/s1234567/datahub/design/deployment/v1/commits
/external-api/api/s1234567/datahub/design/deployment/v1/promotions
/external-api/api/s1234567/datahub/design/deployment/v1/environments/DEV/instances/**
/external-api/api/s1234567/datahub/design/code/v1/preview

Add one environments/<ENVIRONMENT>/instances/** line for each runtime environment the key may deploy to, with the name exactly as shown in ADE (DEV is an example). Leave out environments, such as production, that the key must not deploy to.

And separate rule for GET:

/external-api/api/s1234567/datahub/design/metadata/v1/entities/formats/yaml
/external-api/api/s1234567/datahub/design/metadata/v1/entities/formats/yaml/schema
/external-api/api/s1234567/datahub/design/metadata/v1/packages/formats/json
/external-api/api/s1234567/datahub/design/metadata/v1/graphql
/external-api/api/s1234567/datahub/design/metadata/v1/search
/external-api/api/s1234567/datahub/design/metadata/v1/search/**
/external-api/api/s1234567/datahub/design/code/v1/preview
/external-api/api/s1234567/datahub/design/deployment/v1/commits
/external-api/api/s1234567/datahub/design/deployment/v1/commits/**
/external-api/api/s1234567/datahub/design/deployment/v1/promotions
/external-api/api/s1234567/datahub/design/deployment/v1/deployments
/external-api/api/s1234567/datahub/design/deployment/v1/deployments/**
/external-api/api/s1234567/datahub/design/deployment/v1/environments/**
/external-api/api/s1234567/datahub/design/pingpong/v1
/external-api/api/s1234567/datahub/design/me

Runtime Environments

Base path: /external-api/api/<tenant>/<installation>/<env>/

Endpoint	Methods	Purpose
`dagger/v2/dags/*/dag-runs`	GET, POST	Trigger DAGs and check run status
`run-ids/v1/ids`	GET, POST, DELETE	Manage run IDs for delta loading (`ada run-ids`)
`metadata/v1/search/workflows`	GET	Workflow (scheduling chain) graph.
`pingpong/v1`	GET	Connectivity test
`metadata/v1/graphql`	GET	Metadata discovery
`me`	GET	Authentication to MCP Server

Follow the same rules as for Design-environment, and add separate authorization rules POST and GET.

For example, adding POST for dev environment:

/external-api/api/s1234567/datahub/dev/dagger/v2/dags/*/dag-runs
/external-api/api/s1234567/datahub/dev/run-ids/v1/ids

And separate rule for dev environment GET:

/external-api/api/s1234567/datahub/dev/dagger/v2/dags/*/dag-runs
/external-api/api/s1234567/datahub/dev/run-ids/v1/ids
/external-api/api/s1234567/datahub/dev/metadata/v1/search/workflows
/external-api/api/s1234567/datahub/dev/pingpong/v1
/external-api/api/s1234567/datahub/dev/metadata/v1/graphql
/external-api/api/s1234567/datahub/dev/me

And separate rule for dev environment DELETE:

/external-api/api/s1234567/datahub/dev/run-ids/v1/ids

Read-only access

To restrict ADA to read-only operations (pull, search, preview and status checks, but no push or deploy), give the key only the following rules. Rules grant access, so anything not listed is refused.

GET on every endpoint listed above, in the Design and the runtime environment sections.
POST on code/v1/preview only. This generates SQL and does not change anything in ADE.

For a read-only key, do not add these rules. Each one allows a change:

Rule	What it would allow
POST `metadata/v1/entities/formats/yaml`	Push entities (`ada push`; also `ada push --dry-run`)
POST `metadata/v1/packages/formats/json`	Push config packages
POST `deployment/v1/commits`	Create commits
POST `deployment/v1/promotions`	Promote commits
POST `deployment/v1/environments/<ENVIRONMENT>/instances/**`	Start deployments
POST `dagger/v2/dags/*/dag-runs`	Trigger DAG runs
POST, DELETE `run-ids/v1/ids`	Add and delete run IDs