Critical Data Element (CDE) API

The CDE API lets you programmatically manage Critical Data Elements and their full lifecycle — from creation and governance through to physical data mapping, risk assessment, and certification. It is a separate microservice from the core Alation platform and has its own base path and its own authentication mechanism.

⚠️

The CDE API uses a different authentication flow from all other Alation APIs.

Unlike every other Alation API endpoint (which accepts your Alation API token directly), the CDE API requires a two-step token exchange before you can call any CDE endpoint. The header key names are also different at each step. This is not obvious from the endpoint reference alone — read the Authentication section below before making your first request.

Base URL

All CDE API endpoints are served from a separate path:

{protocol}://{alation_domain}/cde-service/integration/

Replace {alation_domain} with your Alation instance URL (for example, your-company.alationcloud.com).

Authentication

CDE authentication works in two steps. Both steps use different header key names from each other and from the rest of the Alation API.

Step 1 — Exchange your Alation API token for a CDE token

Call the auth endpoint, passing your existing Alation API token (refresh token or access token) in the request header using the key token.

POST /cde-service/integration/auth/

📘

Where to get your Alation API token

If you do not already have one, generate an Alation API token using the standard Alation token endpoint. See Authentication into Alation APIs for instructions.

Example request (curl):

curl -X POST "https://{alation_domain}/cde-service/integration/auth/" \
  -H "token: {your_alation_api_token}"

Example request (Postman):

In the Headers tab, add:

Response:

The endpoint returns a plain string — your CDE token — valid for 24 hours.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Store this token. You will use it in the header of every subsequent CDE API call.

Step 2 — Call CDE endpoints using the CDE token

For all requests to CDE endpoints (/cde/, /standard/, /job/, /user/), pass the token from Step 1 in the header using the key CDEToken.

⚠️

The header key name is CDEToken, not token and not Authorization.

Using the wrong key name will result in a 401 Unauthorized or 400 Bad Request response even when your token is valid.

Example request (curl):

curl -X GET "https://{alation_domain}/cde-service/integration/cde/" \
  -H "CDEToken: {your_cde_token}"

Example request (Postman):

In the Headers tab, add:

Authentication summary

Token validity: The CDE token expires after 24 hours. When it expires, repeat Step 1 to obtain a new token.

Endpoints

The CDE API is organized into four resource groups.

Critical Data Element (CDE)

The core resource. Covers the full CDE lifecycle.

Standard (Overlay Policies)

Manage governance standards that can be applied to CDEs.

Job

Track and manage long-running asynchronous operations (bulk creation, scoring, data mapping).

User

Look up Alation users for assignment to CDEs and Standards.

Key concepts

CDE lifecycle statuses

A CDE moves through a defined set of statuses. Use GET /cde/{id}/next_status/ to programmatically check which transitions are valid from the current state before calling POST /cde/{id}/status/.

To revert a CDE back to DRAFT, use the dedicated POST /cde/{id}/recall/ endpoint instead of the status-change endpoint.

Standard types

When creating or filtering Standards, the type field accepts the following values:

Physical Data Elements (PDEs)

PDEs link a CDE to the actual physical columns or fields in your data sources. Each PDE has a relationship to the CDE:

Use POST /cde/{id}/pde/query/ to filter PDEs by name, relationship type, or path within a CDE rather than retrieving all PDEs at once.

Asynchronous jobs

Some operations — including bulk CDE creation and score calculations — are processed asynchronously. These operations return a job_id immediately. Use GET /job/{id}/ to poll the job status until it reaches FINISHED, ERROR, or CANCELED.

Pagination

List endpoints (/cde/, /standard/, /job/, /user/) support pagination via query parameters:

All list responses include a total_count field alongside the items array, so you can calculate the total number of pages without an additional request.

Error responses

Related resources

• Authentication into Alation APIs — how to obtain your Alation API token (required before Step 1 above)
• Create Public CDE API token — the auth endpoint reference
• API throttling — rate limits that apply across Alation APIs
• API error codes — general Alation API error reference