Scoped Service Credentials for Integrations

Service credentials give an integration an Organization-owned identity independent of a human issuer. They are implemented behind default-off installation availability (API_SERVICE_CREDENTIALS_ENABLED) and explicit Organization enablement. Automated tests do not validate a deployment. Keep them off until you have validated the application, workers, administration UI and operation matrix in your own environment.

An Organization administrator uses API keys → Service identities (/app/data/api-keys) to enable Organization access, select agents or Teams, choose a scope ceiling, and issue a credential with an explicit expiry. Creation, edits, issuance, rotation and enabling require both API-key management and Organization-wide agent-management capabilities. API-key administrators retain list, disable and revoke access, including during installation rollback. Mutations require a human session, CSRF, current Organization SSO policy and recent authentication evidence. A service cannot administer itself.

Send X-Api-Key: <service_credential> to REST. Remote MCP also accepts Authorization: Bearer <service_credential>. Conflicting credential headers are rejected. HTTPS is required except when the installation explicitly runs with DT_RELEASE_ENV=local. Tokens begin dt_svc_, contain a random version identifier and 256 bits of random secret, and are returned once. Store them in a trusted secret manager; no old token can be retrieved. The database stores only a domain-separated HMAC-SHA256 digest keyed by the installation's dedicated secret. Lost issuance responses require deliberate rotation or revocation; credential issuance does not replay plaintext secrets.

Recognized service credentials in an unsupported authorization transport do not fall back to a human session, even if the client also carries a valid session cookie. Service administration rejects machine credential headers and uses the human session explicitly.

Existing member-issued keys retain their original issuer-authority rules and credential-specific replay namespace. Service credentials do not impersonate the creator, an Organization administrator or a Django user. Their audit actor identifies the service and authenticated version; the creator is historical sponsorship. External Security Halt, SCIM and machine integration credentials retain their separate protocols and permissions. A general service credential cannot request or release an emergency halt.

Console administration targets the displayed Organization even if the session workspace changes while a form is open. Editing an identity with a custom scope set preserves those scopes unless the administrator selects another profile. Last successful use excludes HTTP errors, MCP tool failures and JSON-RPC protocol/resource errors, including errors returned with HTTP 200.

Resource authority

The three agent scope labels are ceilings, intersected with the following explicit operation matrix and current resource grants. An empty agent/Team selection authorizes no agents. There is no Organization-wide wildcard.

• An explicit agent grant applies while the agent belongs to the sponsoring Organization. Moving within that Organization retains the explicit grant. A transfer outside it removes the grant through the supported ownership services; returning the agent requires a new grant.
• A Team grant includes current and future agents in that exact active Team and Organization. Moving an agent out, disabling/deleting the Team or changing ownership removes Team-derived access. Explicit agent grants remain independent of Team availability.
• Collections filter before pagination and counts. Detail errors for inaccessible resources are generic. Both peer endpoints must be granted for link reads and writes. Shared filespaces require every participating agent to be granted; file and attachment references also retain their normal ownership and malware-scanning checks.
• Credential expiry/revocation, identity disable/revocation, Organization deactivation, Organization service-access disablement and installation disablement deny future use. Scope/grant removal also denies stored response replay. Creator departure alone does not revoke the service.

Core REST matrix

All paths below are relative to /api/v1/agents/ unless marked absolute. The core matrix is extended by the scoped application-request, automatic-event/webhook, file, named-schedule and reporting workflows described below. Legacy browser profiles/tasks, ping, agent creation, contacts, inbound webhook management, webhook-secret rotation, broad timelines/debug traces, timeline waits, pending actions and legacy channel messages remain unavailable to service credentials. Unknown operations fail closed. Application-request revision waits are part of the supported scoped request workflow.

Method and path	Scope ceiling	Optional replay
GET /, GET archived/, GET {id}/	agents:read	No
GET {id}/processing-status/	agents:read	No
POST {id}/schedule/preview/	agents:read	No
PATCH or PUT {id}/	agents:manage	Yes
DELETE {id}/, POST {id}/restore/	agents:manage	Yes
POST {id}/activate/, POST {id}/deactivate/	agents:manage	Yes
POST {id}/stop/	agents:operate	Yes
GET {id}/peer-links/, GET {id}/peer-links/{link_id}/	agents:read	No
POST {id}/peer-links/, PATCH or DELETE {id}/peer-links/{link_id}/	agents:manage	Yes
GET /api/v1/operations/{operation_id}/ (absolute path)	agents:read plus original-operation scope	No; safe retained outcome read

Configuration accepts only name, charter, schedule, is_active, preferred_llm_tier, whitelist_policy, contact_approval_mode and proactive_opt_in. Unsupported and read-only fields are rejected for services. Detail representations return empty personal-server/integration discovery lists. Changing intelligence tier through a service updates configuration for subsequent work without publishing the member-key adapter's immediate processing trigger. This keeps service-credential configuration separate from application-request application work submission. Existing schedule and lifecycle services continue to govern future scheduled work and previously accepted, ownership-bound broadcasts.

Stop remains ordinary Stop: it signals processing and cancels currently linked Organization-owned browser tasks; it is not emergency containment. Credential revocation is an access change, not an execution stop or recall of external actions.

Initial MCP matrix

initialize, ping, tool/resource discovery and authenticated resource reads use the normal transport contract. tools/list returns only the operations below that fit the current scope ceiling. Service credentials cannot use user_id or organization_id targeting overrides.

Tools	Scope ceiling	Optional replay
list_agents, get_agent, list_agent_links	agents:read	No
list_agent_files, read_agent_resource, resources/read	agents:read	No
upload_agent_file	agents:operate	Yes
update_agent, archive_agent, link_agents, unlink_agents	agents:manage	Yes

MCP creation, messaging, timeline/debug/wait tools, configuration-options discovery and all workspace, native integration, OpenAPI and machine-identity control tools are excluded. Unsupported tools return isError: true with explicit denial. Resource failures remain generic. A denied response replay can return HTTP 403 or 404; clients must inspect the HTTP status as well as JSON-RPC tool results.

Rotation, replay and bounds

Every version expires no later than 90 days after issuance; deployment API_SERVICE_CREDENTIAL_MAX_DAYS can lower the maximum for new issuance. Existing stored deadlines remain authoritative; revoke versions or disable access to end their authority immediately. Rotation can retain one old version for a selected overlap of 0–24 hours, capped by its original expiry. Zero revokes it immediately. Rotating again ends any existing overlap before starting the next one. Either version can be revoked immediately. Identity revocation is permanent; disablement is reversible.

For supported mutations, Idempotency-Key identifies an operation within the service identity, so rotation preserves the replay namespace. Identical method, path and payload replay the encrypted retained result; changed input returns 409. Default retention is 24 hours (API_IDEMPOTENCY_RETENTION_HOURS); expired records can execute again. Successful receipts retain all involved agent IDs, and current authority must still cover them before replay. Failures are not stored as successful service receipts. Retrying archive/restore must still satisfy the current Organization and explicit grants.

Authority transactions serialize service operations within an Organization. The order is Organization, service identity, credential, selected agents in UUID order, granted Teams in UUID order, then operation records. Selections are frozen for that transaction; Team additions become visible on the next call. Ownership changes and grant/lifecycle edits use the same Organization admission lock. This favors correctness over throughput; no service throughput or availability target is published. At most 1,000 explicit agent/Team selections are accepted per identity edit. Existing file-size, pagination, malware, license and runtime restrictions remain in force.

Deployment and pepper rotation

1. Apply additive migration 0577_api_service_credentials with service availability off. Preserve identity/version/grant/audit/replay rows during rollout and rollback.
2. Configure API_SERVICE_CREDENTIAL_SECRET using at least 32 bytes of independent high-entropy secret material. Keep it outside logs, source and generated assets. Do not reuse SECRET_KEY or the encryption key.
3. Upgrade/drain application and relevant worker processes and build the administration/documentation assets in an owned, isolated validation environment. Prepare a disposable Organization's selected/unselected resources. Keep maintained installations off.
4. Enable availability and the disposable validation Organization only inside that environment, issue fixture credentials and observe creator departure, rotation/expiry, nested files/peers, concurrent revoke/grant/ownership changes and response replay. After qualification and review are accepted, maintained availability and each Organization gate require deliberate enablement. No maintained deployment has been qualified by this implementation's automated checks.

To replace the pepper, first disable installation availability and drain old application processes. Replace the dedicated secret across the installation; all prior digests then fail authentication. Preserve historical records. After deploying the new secret, enable issuance for a validation Organization, revoke old versions and issue replacements through recent-authenticated human administration. Requalify before broader access. Pepper replacement has no overlap contract; normal credential rotation with an unchanged pepper supplies bounded continuity.

Rollback disables new service authentication and issuance while retaining human list/disable/revoke controls and historical attribution. It does not erase receipts, replay accepted work, cancel historical input or relax emergency gates. Destructive migration rollback is not an operational recovery procedure.

Retained service, version and lifecycle references protect hard deletion of their Organization/principal records. Disable/revoke access and retain these records rather than using Organization deletion as credential cleanup. A separate governed retention procedure would be needed for destructive removal; it is not part of service-credential configuration.

Retained allowed mutations expose Operation-Id and Idempotency-Expires-At. The identity-scoped GET /api/v1/operations/{operation_id}/ returns safe resource/outcome metadata while requiring read scope, the original operation scope and current grants; no stored response/secret body is returned. A rotated authorized credential retains that operation ID. This retry protocol does not itself expand authority; scoped outbound subscriptions use the automatic-event extension below. Browser-task creation and human decisions remain unavailable to services.

Scoped REST extensions

Each extension retains current resource grants, original principal/ownership and its own deployment gate. Enabling service credentials alone does not enable these workflows.

Workflow	Supported service surface and scope	Additional contract
Application requests	Create with agents:operate; list, detail, responses, result and revision waits with agents:read	API_APPLICATION_REQUESTS_ENABLED for new input; required replay key and principal-scoped reads. Structured result admission also requires API_STRUCTURED_RESULTS_ENABLED.
Automatic events and delivery recovery	Source events and delivery list/detail with agents:read; outbound subscription create/detail/update/delete and deliberate redelivery with agents:manage	Automatic capture requires API_AUTOMATIC_AGENT_EVENTS_ENABLED. Services subscribe only to supported automatic types for their own requests; no wildcard, pending-action or widened visibility. Redelivery requires a replay key; see the event guide for retained recovery rules when capture is disabled.
REST files	Inventory, status and file/attachment downloads with agents:read; upload and replacement with agents:operate	API_REST_FILES_ENABLED for new writes, required replay keys, exact-generation and malware/retention checks. Shared filespaces require all participating agents to be granted.

Named-schedule extension

The named-schedule REST matrix is an explicit resource-bounded extension: GET collection/detail requires agents:read; create/PATCH/delete/enable/disable requires agents:manage, current agent/Team grants and the default-off configuration gate for new writes. Mutations require a retry key and existing-schedule changes an ETag. It neither expands grants nor confers Organization authority. Member-only creation, workspace/configuration/integration discovery and binding controls remain excluded for services; MCP setup control exclusions remain unchanged. This matrix requires validation in your deployment.

Scoped reporting

Explicit usage:read and audit:read scopes add only the four operational read endpoints. Existing profiles retain their original scopes. Reporting sponsorship requires the corresponding Organization capabilities during create/edit/enable/rotation, and every read intersects the advertised operation with current agent/Team grants and retained original ownership. Unknown historical run ownership cannot be borrowed from current agent state.