Coming soon · Contract draft

Developer Platform Governance

Planned

A canonical product-object catalog that reconciles REST, GraphQL, MCP, webhooks, scopes, principals, and Connected App grants without overstating runtime availability.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Developer Platform capability catalog and authorization policy

Contract posture

P0 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Platform + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 0 · Make platform claims true

Contract dependencies

• Principal × scope grantability matrix
• Versioned interface catalog
• Transactional audit and event contracts

What this unlocks

Discover supported capabilities

Read a stable domain model for developer platform governance without depending on GUI routes or database shapes.

Validate grants before integration

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Track contract publication

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Developer Platform Governance exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftreviewedpublishedsuperseded

From	To	Command	Authority
draft	reviewed	Approve contract	Developer Platform maintainers
reviewed	published	Publish catalog	Developer Platform maintainers
published	superseded	Publish replacement	Developer Platform maintainers

Lifecycle invariants

• Published availability is backed by runtime tests.
• Grantability is expressed per principal and scope.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Interface availability and version metadata
• Principal × scope × endpoint grantability
• Published schema and catalog parity

Explicitly not building

• Mirroring internal GUI routes
• Treating documentation as runtime evidence without tests
• Exposing tokens, secrets, or policy internals

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Read-only capability, schema, version, and grantability resources

Customers need one truthful way to discover what exists and what their principal can actually call.

keep

OpenAPI, GraphQL schema publication, and MCP help as discovery surfaces

These describe supported contracts without becoming domain mutation authorities.

remove

Customer create, update, or publish operations for platform contracts

DigitalStack owns publication; customers consume the catalog but do not mutate platform definitions.

Interface plan

REST API

Planned

Versioned developer platform governance resources, commands, idempotency, and operation status.

Read only

GraphQL

Planned

Composable, read-only developer platform governance discovery through the canonical service.

Read only · no customer mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read only

Webhooks

Planned

Past-tense developer capability lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Consumer app registrations plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /developer-capabilities	developerCapability(id: ID!): DeveloperCapability	get_developer_platform_governance	—	Developer Platform capability catalog and authorization policy
Primary command	Not exposed	Not exposed	Not exposed	developer_capability.created	Developer Platform capability catalog and authorization policy

Proposed scopes

Proposed scopes are not grantable yet.

developer-platform:readplanned scope

Read governed developer platform governance resources.

developer-platform:writeplanned scope

Create and edit bounded developer platform governance fields.

developer-platform:operateplanned scope

Run explicit developer platform governance lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Developer Platform capability catalog and authorization policy; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/developer-capabilities

List developer platform governance

Return an authorized, paginated collection with stable filters and provenance.

developer-platform:read

GET/api/v1/developer-capabilities/{id}

Retrieve DeveloperCapability

Return canonical detail, lifecycle state, permissions, and allowed actions.

developer-platform:read

GET/api/v1/developer-capabilities/{id}/grantability

Get capability grantability

Return the principal, scope, plan, and rollout requirements for one capability.

developer-platform:read

Execution: Synchronous

GET/api/v1/developer-schemas

List published schemas

List versioned OpenAPI, GraphQL, webhook, and MCP schema artifacts.

developer-platform:read

Execution: Synchronous

List developer platform governance

Planned request

curl --request GET \
  --url "https://www.digitalstack360.com/api/v1/developer-capabilities" \
  --header "Authorization: Bearer $DSTACK_API_KEY"

Planned response

{
  "data": [
    {
      "id": "developer-platform-governance_123",
      "status": "available",
      "version": 1
    }
  ]
}

GraphQL

Proposed graph

Planned

Types

DeveloperCapability

DeveloperCapabilityConnection

DeveloperCapabilityChangeProposal

Operation

Queries

developerCapability(id: ID!): DeveloperCapability

developerCapabilityList(filter: DeveloperCapabilityFilter, pagination: PaginationInput): DeveloperCapabilityConnection!

No GraphQL mutations planned

Read only. Customer callers cannot create, edit, publish, or administer these DigitalStack-owned resources.

Planned GraphQL query

query DeveloperCapabilityDetail($id: ID!) {
  developerCapability(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Developer Platform Governance

get_developer_platform_governance

Planned

Read the authorized developer platform governance state, provenance, and allowed actions.

Scope: developer-platform:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Planned agent workflow

User: Explain the current developer platform governance for a project I can access.

1. Call get_developer_platform_governance to read the authorized state, contributing evidence, and provenance.
2. Summarize the facts and their evidence for the user.

This is a read-only surface: there is no draft, apply, or command tool to call.

Webhooks

Proposed event catalog

Planned

Event types

developer_capability.createdplanned event

A canonical DeveloperCapability was created.

payload: developer_capability_id, status, created_at

developer_capability.updatedplanned event

Governed DeveloperCapability fields changed.

payload: developer_capability_id, changed_fields, version, occurred_at

developer_capability.publishedplanned event

The publish command completed.

payload: developer_capability_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "developer_capability.published",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "developer_capability",
    "id": "developer_capability_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "developer_capability_id": "developer_capability_123",
    "prior_status": "draft",
    "status": "published"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded developer platform governance proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Consumer app registrations

Consumer application

Bind an app identity to reviewed grants and interface versions.

Authority: Registration does not grant scopes until a workspace authorizes them.

Open contract decisions

Resolve before implementation approval

• Should schema artifacts use one global version or independent interface versions?

Proof obligations

Must remain true	Failure indicator
Developer Platform capability catalog and authorization policy remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.