Authentication and request conventions

Prepare an identity

Confirm license, functional permissions, and object scope for each target module. Systems, sources, standards catalogs, asset catalogs, and quality issues have separate access scopes. An administrator's visibility does not establish an integration identity's access.

Deployments can use gateways, SSO, or tokens. The definitions do not declare a common securitySchemes, so this guide does not assume Bearer, Basic, or a fixed custom header. Have the administrator confirm credential placement, lifetime, and revocation. Personal browser sessions are unsuitable as a permanent unattended integration design.

Current identity and tokens

In Personal Workspace > Token Management, generate a short-lived token for temporary testing or a permanent token for a controlled service account. Save it in enterprise secrets management; the complete credential may not be displayed again. Assign an owner, purpose, rotation cycle, and revocation record.

These are authenticated identity-management endpoints, not anonymous password-to-token exchanges:

Method and complete path	Purpose	Inputs or response
GET /user/usermanagement/users/details/self	Verify current identity	Current user details; retain only needed identifiers
POST /user/token/getTokens	List current user's tokens	id, name, expireHours, expiresAt; may include sensitive credentials
POST /user/token/generateTokens	Create token	Body name String, expireHours Long; policy controls availability and lifetime
POST /user/token/updateToken	Update token configuration	Deployed UserTokenUpdateDto
POST /user/token/deleteToken	Revoke token	Deployed UserTokenUpdateDto; check affected consumers

Tokens do not expand account permissions. Keep credentials out of source code, request logs, screenshots, and documents.

URLs, methods, and media types

Use the deployment entry point plus complete path. Swagger servers can contain internal nodes; obtain the approved external entry point. Many queries use POST. A method alone does not identify a write, and historical multi-method declarations do not make DELETE or PUT safe query aliases.

Use application/json for JSON, preserve Query/Path/Body locations, and follow multipart upload contracts. Exports may return binary data or asynchronous identifiers.

This metadata search uses an approved cookie file for session-based testing. Replace authentication according to deployment. DAM_BASE_URL is the actual entry point.

curl --fail-with-body --request POST \
  --cookie "$DAM_COOKIE_FILE" \
  --header 'Content-Type: application/json' \
  --data '{"currentPage":1,"pageSize":20,"keyword":"customer","types":["TABLE"]}' \
  "$DAM_BASE_URL/metadata/entities/searchMetadata"

The example preserves HTTPS certificate validation. Use a trusted enterprise certificate chain.

Pagination and responses

Interface	Request fields	List and total
Metadata, sources, published standards	Body currentPage, pageSize	content, totalItems
Reference codes	Body currentPage, pageSize	data, total
Technical quality rules	Body currentPage, pageSize	ruleList, total
Assets	Body pageNum, pageSize	status, msg, open data structure
Published security assets	Body pageNo, pageSize; schema defaults 1 and 10	status, msg, data
Quality issue rows	Query currentPage, pageSize, starting at 1	rowNames, rowData, totalRow
Generic jobs	Conditions and nested page	content, totalElements, number
Optional unified asset search	Body cursor, limit	items, nextCursor, hasMore

Confirm page origins rather than inferring them from names. Sample open Maps before adapting them; do not invent fields such as data.list.

Object identity

• Retain system categoryId, source modelId, object objectId, source system, and schema.
• Metadata search returns id; detail and column paths use objectId. Verify their mapping.
• Catalog catalogId, structure structureId, asset assetId, and underlying objectId differ.
• Standard domainId differs from domainCode; metrics and reference codes have separate identifiers.
• SQLink node id is String, not DAM's numeric objectId; establish a verified mapping.
• Parse and store Long identifiers without JavaScript safe-integer precision loss.

Errors, retries, and logging

Condition	Action
401 or login redirect	Reauthenticate and detect HTML instead of treating it as JSON
403 or invisible object	Check identity, module, and scope
400 or 404	Check prefix, method, types, and existence
429, busy gateway, temporary 5xx	Bounded backoff for reads; 429 support depends on deployment
200 with business failure	Inspect status, msg, and actual error structure
Custom status such as 599	Retain a redacted summary for the service administrator

No common idempotency key has been verified for writes or job starts. After timeout, query actual status before resubmitting. Log time, method, path, redacted conditions, IDs, and HTTP/business state. Remove credentials, passwords, and raw issue data.

Acceptance checks

1. Query an authorized and an unauthorized sample with the integration identity.
2. Compare names, sources, states, counts, and pagination termination with the UI.
3. Test expired credentials, missing input, missing objects, and service failures.
4. Record deployment build and contract; repeat scenarios after upgrades.