Practical integration

Exercise the complete lifecycle

Move from confidential application credentials to a workspace-scoped request, durable processing, signed events, usage review, and credential rotation.

Integration journey

One end-to-end acceptance path

01RegisterCreate a confidential application and grant a test workspace.

02AuthorizeRequest a REST or MCP audience token with approved scopes.

03ExecuteUpload, process, query, summarize, or run a governed workflow.

04OperateReceive events, inspect usage and traces, then rotate credentials.

Client Credentials

Obtain a REST API token

Service token

curl -sS -X POST https://auth.docintel.adar.agomoniai.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=workspaces:read documents:read knowledge:query" \
  --data-urlencode "resource=https://docintel.adar.agomoniai.com/api/v1"

Client Credentials returns a short-lived access token, not a refresh token. Obtain a new token after access or credential policy changes.

Workspace request

Verify identity and documents

Workspace-scoped read

curl -sS https://docintel.adar.agomoniai.com/api/v1/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-DocIntel-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" | jq

Verify negative paths too

An ungranted workspace must return HTTP 403, an MCP-audience token must be rejected by REST, and an unapproved scope must not be issued.

Knowledge Academy

Ground a Tutor in one lesson

Resolve scope and ask

# Inspect exactly which embedded assets support the selected lesson
curl -sS "$API/learning/courses/$COURSE_ID/scope?module_id=$MODULE_ID&lesson_id=$LESSON_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-DocIntel-Workspace-ID: $WORKSPACE_ID" | jq

# Stream an evidence-grounded Tutor response from that scope only
curl -sS -N -X POST "$API/learning/courses/$COURSE_ID/tutor/query/stream" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-DocIntel-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  --data "$(jq -cn --arg module "$MODULE_ID" --arg lesson "$LESSON_ID" \
    '{question:"What is discussed in this lesson?",module_id:$module,lesson_id:$lesson,history:[],response_language:"en",redact_pii:false}')"

Use learning:read to inspect courses and scope, learning:participate for Tutor, study, quizzes, and questions, and learning:manage for curriculum, enrollment, and content mapping.

Durable processing

Design for asynchronous completion

Create signed uploadUpload to cloudCompleteMonitorWebhook

Large document and video bytes move directly to cloud storage. Store the returned document and operation IDs, monitor bounded progress, and subscribe to lifecycle events rather than holding an interactive request open.

Quota check

Honor operational headers

Inspect headers

curl -sS -D - -o /tmp/docintel-body.json \
  https://docintel.adar.agomoniai.com/api/v1/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-DocIntel-Workspace-ID: $WORKSPACE_ID"

jq . /tmp/docintel-body.json

Inspect X-DocIntel-Usage-Units and any X-RateLimit-* headers. On HTTP 429, honor Retry-After.

Three client starters

Use the same contract in familiar languages

Python

Service automation

Instantiate the starter with base URL, access token, and optional team workspace ID.

Python guidance

JavaScript

Node integration

Use the fetch-based client and keep OAuth secrets outside browser code.

JavaScript guidance

Java

Enterprise services

Use the standard HTTP client starter and centralized application credential handling.

Java guidance

Acceptance checklist

Prove the integration boundary

Correct client and audienceOnly approved scopes issuedOnly granted workspaces accessibleDurable operation reaches terminal stateWebhook signature verified and event deduplicatedUsage and trace appear for the applicationQuota produces structured HTTP 429New secret works and revoked secret fails