Coming soon · Contract draft

Organization, People & Access

Planned

A least-privilege organization graph and lifecycle contract for people, membership, roles, grants, permission requests, and federated identity.

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

Organization access-control and federated identity services

Contract posture

P2 · 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 3 · Organization administration

Contract dependencies

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

What this unlocks

Integrate member lifecycle

Read a stable domain model for organization, people & access without depending on GUI routes or database shapes.

Explain effective access

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

Route access requests

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

Lifecycle and invariants

Organization, People & Access exposes a bounded lifecycle with explicit commands and named authority at every transition.

invitedactivesuspendedremoved

From	To	Command	Authority
invited	active	Accept invitation	Organization access-control service
active	suspended	Suspend member	Organization access-control service
suspended	active	Restore member	Organization access-control service
active	removed	Remove member	Organization access-control service

Lifecycle invariants

• Product grants remain DigitalStack-owned.
• Agents may request or explain access but never grant it.

Authority boundaries

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

DigitalStack owns

• DigitalStack membership and role assignment
• Effective access explanation
• SSO connection and incident state

Explicitly not building

• Raw policy graph for ordinary callers
• Silent role or grant changes by agents
• HR data unrelated to product access

Surface decisions

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

add

Invitations, membership, role changes, access requests, and effective-access explanation

Enterprise administrators need a governed lifecycle rather than raw policy-table access.

keep

Strict admin/self boundaries and attributable access decisions

Read and mutation authority differs substantially by principal.

remove

Generic member creation and raw policy-graph APIs

Membership begins through an invitation or identity lifecycle; internal policy structure is not a public model.

Interface plan

REST API

Planned

Versioned organization, people & access resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable OrganizationMember reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and human-request tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense organization member lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Okta / Entra / HRIS 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 /organization/members	organizationMember(id: ID!): OrganizationMember	get_organization_access	—	Organization access-control and federated identity services
Primary command	PATCH /organization/members/{id}	draftOrganizationMemberChange(input: DraftOrganizationMemberChangeInput!): OrganizationMemberChangeProposal!	draft_organization_access_change	organization_member.created	Organization access-control and federated identity services

Proposed scopes

Proposed scopes are not grantable yet.

organization:readplanned scope

Read governed organization, people & access resources.

organization:writeplanned scope

Create and edit bounded organization, people & access fields.

organization:operateplanned scope

Run explicit organization, people & access lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Organization access-control and federated identity services; 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.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

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/organization/members

List organization, people & access

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

organization:read

GET/api/v1/organization/members/{id}

Retrieve OrganizationMember

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

organization:read

PATCH/api/v1/organization/members/{id}confirmation

Update OrganizationMember

Update bounded editable fields using optimistic versioning.

organization:write

POST/api/v1/organization/members/{id}/change-roleconfirmation

change role OrganizationMember

Run one explicit domain command after validation and authorization.

organization:operate

POST/api/v1/organization/invitationsconfirmation

Invite an organization member

Create an expiring, attributable invitation.

organization:operate

Execution: Synchronous
Idempotency: Required

POST/api/v1/organization/access-requestsconfirmation

Request access

Create a request for an authorized human decision.

organization:write

Execution: Synchronous
Idempotency: Required

change role a OrganizationMember

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/organization/members/organization_member_123/change-role \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: organization-access-change-role-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "organization_member_123",
    "status": "role_changed",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

OrganizationMember

OrganizationMemberConnection

OrganizationMemberChangeProposal

Operation

Queries

organizationMember(id: ID!): OrganizationMember

organizationMemberList(filter: OrganizationMemberFilter, pagination: PaginationInput): OrganizationMemberConnection!

Mutations

draftOrganizationMemberChange(input: DraftOrganizationMemberChangeInput!): OrganizationMemberChangeProposal!

Planned GraphQL query

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

MCP / Agent API

Proposed tools

Planned

Get Organization, People & Access

get_organization_access

Planned

Read the authorized organization, people & access state, provenance, and allowed actions.

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

Draft Organization, People & Access change

draft_organization_access_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: organization:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Request Organization, People & Access action

request_organization_access_action

Planned

Prepare an authorized human action request without executing the high-risk command.

Scope: organization:operate
Input: Proposal id, expected version, named decision maker, and reason.
Output: A pending human-action request and audit reference.
Write boundary: The agent cannot execute the final command.

Planned agent workflow

User: Review the proposed organization, people & access change and help me apply it.

1. Call get_organization_access to inspect current state, provenance, and allowed actions.
2. Call draft_organization_access_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. Call request_organization_access_action so an authorized human can decide.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

organization_member.createdplanned event

A canonical OrganizationMember was created.

payload: organization_member_id, status, created_at

organization_member.updatedplanned event

Governed OrganizationMember fields changed.

payload: organization_member_id, changed_fields, version, occurred_at

organization_member.role_changedplanned event

The change role command completed.

payload: organization_member_id, prior_status, status, occurred_at

Planned event example

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

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded organization, people & access proposals through MCP.

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

Okta / Entra / HRIS

Source connector

Supply identity and employment lifecycle facts.

Authority: DigitalStack remains authoritative for product grants and workspace membership.

Open contract decisions

Resolve before implementation approval

• Which role and grant changes require step-up authentication?

Proof obligations

Must remain true	Failure indicator
Organization access-control and federated identity services 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.