> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent connection API and OAuth
> Separate owner governance from scoped execution, handle OAuth challenges and recover recorded operations.
**Live.** This area is documented as current, user-reliable behavior.
## Goal
Integrate the scoped connection API without treating a client credential as owner authority.
## Prerequisites
* A compatible StackShift backend with connection admission enabled for new grants.
* Owner authorization for governance requests, or the scoped connection credential for execution requests.
* A client that supports the advertised Streamable HTTP and OAuth mechanisms. Deployed MCP integrations are owner-tested; verify each requested resource operation from its controller evidence.
## Workflow
Discover the MCP resource metadata and its authorization server using the instance origin.
Authenticate with explicit resource and scopes, S256 PKCE and a registered callback. Complete live browser consent.
Use the issued bearer credential for connection identity, authorized resources and capabilities.
For a missing supported action scope, follow the insufficient\_scope challenge through new explicit owner consent.
Submit an exact operation with a retained Idempotency-Key, then inspect its approval and controller evidence separately.
## Connected skill guidance (next release)
The authenticated MCP connection exposes skill\_read in every discovery family, including connections with no mutation permissions. Call it with \{} to read SKILL.md, then \{"document":"references/external-connections.md"} and the relevant linked guide. The API embeds the canonical skill files, so reading guidance requires no filesystem installation or separate storage service.
Initialization instructions direct the client to fetch the skill before beginning StackShift work. The client decides when to invoke it; connecting is not proof of consumption. Only bundled documents can be read. Existing authentication, resource grants and operation approvals remain unchanged. Deploy the API to expose this tool and reconnect clients to refresh discovery; the worker needs no change for skill retrieval.
## Executable MCP contracts (next release)
operation\_propose advertises consent-filtered discriminated request schemas from the canonical action catalog. Existing-target operations require resource\_id; unbound creation and account-level inspection omit it. Examples use synthetic IDs: replace them with IDs from resource or catalog discovery. The connected database-create contract uses engine and size\_id, matching its controller adapter.
Recipe and preview POST tools derive request shapes from their existing controller DTOs. Required workflow constraints, current permissions, quote checks and independent approval still run through the same REST/service controllers. Schemas and read-only annotations are discovery aids, not authority.
Keep the existing MCP URL for the complete consented surface. For focused discovery, append ?family=databases (or another advertised family). capabilities accepts a family argument and advertises allowed values; core contains shared identity/resource/recovery tools, recipes adds setup tools, and previews adds preview tools. Filtering does not add scopes. An unknown family returns invalid\_request. Choose another family or the original URL when switching tasks.
Use the advertised prerequisite IDs and current resource\_context revision. On uncertain responses, replay the same idempotency key and identical body, then inspect the relevant operation, recipe setup or preview. target\_changed, revision\_conflict and plan\_stale require fresh context and review. idempotency\_conflict requires restoring the original request; capability\_unavailable requires resolving the reported prerequisite. insufficient\_scope requires explicit new owner consent.
The release record distinguishes local schema/SDK tests from deployed client behavior. The controlled comparison measures contract payload tokens and schema defect detection; it is not a live model success-rate or latency claim.
## Infrastructure quote and recorded usage
New direct database creation and scaling proposals retain a server-generated NGN quote with kobo-per-hour components, price fingerprint, exclusions and a 15-minute expiry. The quote is included in the approval and checked again before execution. Changed prices, placement or an expired quote require a new proposal; idempotent retries retain the original quote.
Deployments and scaling on an owner server add no StackShift workload hosting charge. Server rental and separately purchased services retain their own billing. Other unpriced infrastructure stays explicitly unavailable or excluded. AI budgets and existing service limits remain separate; no aggregate infrastructure cap is introduced.
Operation details show the retained estimate alongside recorded infrastructure usage where resource usage exists. Recorded usage includes signed ledger corrections posted since the operation, uses the current NGN settlement contract, and does not claim to be a paid invoice or cost caused exclusively by that operation. No usage rows means unavailable, not zero.
These quote and usage projection changes are local next-release work; existing deployed MCP support remains available.
## Transport and response conventions
Connection REST paths below are relative to /api/v1/agents/connections. MCP remains at /api/v1/agents/mcp. Send credentials in the Authorization bearer header, never in the URL.
Successful connection REST responses wrap their payload in data. OAuth metadata and token responses follow their protocol shape without that wrapper. REST failures use the platform error envelope and a machine-readable code.
New grant admission and direct execution have separate enablement controls. Authorized inspection does not require native Stackie inference, AI credits or an AI subscription. Current resource permissions still apply.
## Owner governance routes
A connection execution credential cannot call these governance routes, decide approvals or edit policy. Broader owner credentials are not interchangeable with the scoped execution credential.
* GET /catalog and GET /catalog/\{client}/setup?scope=... return the canonical client catalog and resolved setup. Public setup uses /api/v1/agent-client-catalog and /api/v1/agent-client-catalog/\{client}/setup; these issue no authority.
* GET /action-catalog returns explicit action descriptors, input/output schemas, resource kinds, approval, effects, funding and configuration availability. GET /action-inventory records canonical registrations and adapters; use capabilities to check availability for the selected resource.
* GET / and GET /\{connectionID} inspect owner connections; POST / creates a restricted headless grant with Idempotency-Key.
* GET /available-resources and GET /available-policies return selectable owner-authorized choices.
* GET /consents/\{consentID} and POST /consents/\{consentID} require a live owner browser session. Decisions also require existing CSRF protection.
* POST /\{connectionID}/revoke revokes authority. POST /\{connectionID}/replace-credential uses a retained Idempotency-Key and does not expand the grant.
* GET /\{connectionID}/operations reads that connection’s operation history through owner governance.
## Scoped execution routes
Discover exact supported action names from the catalog and capabilities endpoints, including typed product inspections and mutations. New operations require explicit consent; existing grants do not expand automatically. Database bindings support private\_read only when a qualified reader endpoint exists; they never fall back to the writer. Read the current capability schema before constructing configuration; unsupported fields and binding permission modes are rejected.
Keep the exact request and key together. Reusing a key for different content conflicts. An accepted operation exposes its stable identity, affected targets, approval, safe result and controller\_operations; inspect controller outcomes before reporting success.
* GET /identity returns the retained connection identity and grant.
* GET /resources and GET /resources/\{kind}/\{resourceID}/context require resource.read and current resource access.
* GET /capabilities returns typed available actions and configuration schemas. Discover active database size choices here.
* GET /resources/project/\{resourceID}/logs requires logs.read and current project authority. Output is bounded and redacted; source unavailability is an error, not empty successful output.
* POST /operations accepts action, optional resource\_id, configuration, optional expected\_resource\_version and native\_ai only for declared native-AI actions, with Idempotency-Key.
* GET /operations and GET /operations/\{operationID} require operation.read and remain connection-scoped.
## Product creation and workspace continuity
grant.creation\_allowances defaults to an empty array. Up to six independent kinds each permit exactly one resource: project with hosted or exact connected\_node placement; database restore target with an independently selected source\_database\_id; hosted wordpress\_site; compute\_instance with selected plan\_id; storage\_bucket with explicit region; or http\_cron\_job. Resource grants alone confer no creation capacity.
WordPress site creation, site/archive import and staging share the same hosted one-site allowance. Staging additionally requires a separately selected hosted source. No operation replenishes the slot or grants unrelated actions on the retained target.
wordpress.archive.import verifies a bounded archive SHA from a ready workspace with same-connection source provenance and an independently selected source project. wordpress.import.resume uses the original import\_execution\_id, package, settings and target, with new exact approval and current source authority; it never creates a second slot.
Allowance responses expose reserved and resource\_id as server-owned fields. A new key does not replenish a reservation after rejection or failure. Lost-response recovery uses the original execution and key; replacement retains or reduces constraints and copies reservation state.
Engineering materialize, inspect, execute, write, tests and source export continue only workspaces proven by a successful creation receipt from the same connection and selected project. Every follow-up has its own idempotency key, admission and approval. Another connection or replacement credential cannot adopt that workspace.
Direct controller actions do not invoke Stackie or consume native inference credits. Native-AI actions declare native\_ai\_schema and require native\_ai: \{funding: account\_ai, budget\_cents: positive integer} within the configured maximum. Existing account funding, BYO and credit gates still apply; a connected client subscription never pays for native calls.
## Native AI and finite controller operations
autonomous.launch uses an already selected project; configure source and environment through separate approved actions first. autonomous.continue retains the same connection, objective, plan, resource caps and original total budget. Revocation, changed approval, expired authority or exhausted budget blocks deferred effects.
project.repair\_policy.configure requires explicit policy expiry, daily repair cap, resource caps and native funding. Its budget is one total across all episodes, not a fresh budget per repair. Expiry is bounded by connection expiry and 30 days. project.repair\_policy.disable is a separate direct action.
project.environment.value.save requires an exact inspected variable/version and accepts only non-secret values. project.secret.rotate uses server-side entropy for an application secret and includes the approved pinned rollout. Provider credentials must use their provider rotation flow; returned pending work is not a completed rotation.
engineering.pull\_request.create accepts at most ten exact files with expected\_blob\_sha and the approved base SHA. It creates a reviewable PR through the existing repository controller; optional auto\_rebuild is verification only. It does not merge the PR.
database.row\.mutate retains primary-key, backup and runtime controls. Database start/stop reports current requested state; it does not invent a unique worker receipt. Asset webhook notification confirms the retained event, not external delivery; creative review confirms proof submission, not approval or publication.
account.usage.inspect is explicitly account-wide and can include billing totals outside selected resources. It requires its own operation consent. Resource discovery and other inspections remain scoped and redact credentials.
## OAuth discovery, consent and refresh
Protected-resource discovery is available at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/api/v1/agents/mcp. Authorization-server discovery is /.well-known/oauth-authorization-server. Use the advertised configured issuer and endpoints.
OAuth endpoints are /api/v1/agents/connections/oauth/register, /authorize, /token and /revoke. The server supports client ID metadata documents and dynamic registration compatibility, authorization-code S256 PKCE, explicit resource audience and rotating refresh credentials.
Consent is bound to the live owner session. A repeated identical decision recovers the recorded outcome without returning another callback code. If the callback was lost, restart client authorization. Conflicting decisions are rejected.
Access credentials last up to 15 minutes and are bounded by connection expiry. Connection grants default to 30 days. A refresh token is not guaranteed; request offline\_access where supported and follow advertised metadata. Refresh replay revokes retained authority.
## Register a public client with an exact callback
When the client setup requires prior registration, choose an available local callback port. Read the selected instance authorization-server metadata and POST public registration metadata to its advertised registration\_endpoint. Do not substitute an unrelated registration service.
Send client\_name, redirect\_uris containing [http://localhost:PORT/callback](http://localhost:PORT/callback), grant\_types containing authorization\_code and refresh\_token, response\_types containing code, and token\_endpoint\_auth\_method set to none. Replace PORT with the chosen numeric port before registering.
Use the returned public client\_id and that exact port in the official client setup controls. A public client ID is configuration metadata, not a secret or execution credential. Registration grants no resource access and needs no owner token or client secret.
Use the client’s supported scope controls to request resource.read and operation.read, plus offline\_access if refresh is needed. Complete client login and owner browser consent separately. Keep authorization codes, callback URLs and issued tokens private.
This server requires an exact registered port for localhost redirects. Its variable-port exception applies only to numeric loopback IP redirects. Consult the catalog for version-specific compatibility and any default metadata-document mismatch.
## Request additional action scope
Initial discovery requests resource.read and operation.read. The proposal tool is discoverable, but missing action authority produces HTTP 403 with a WWW-Authenticate insufficient\_scope challenge naming the exact action and baseline reads before admission.
Start a new OAuth request for the needed scopes and retain other still-needed scopes where the client supports it. The owner explicitly selects resources and actions again. This creates a new connection; it does not silently broaden the old connection or its scope-preserving replacement.
Clients without transport step-up need their supported explicit reauthentication controls or an owner-issued restricted credential. Consult the shared catalog for the precise tested client/version and remaining gaps. Granting action scope still does not approve the eventual proposal.
## History, source availability and recovery
Operation listing separates current from history.items. Use history.next\_cursor for the next terminal-history page; limit bounds that history page. Keep cursors within their original owner/connection query.
source\_status and errors describe independently unavailable current/history sources. Retain last successful data as stale rather than interpreting an unavailable source as empty. Both sources unavailable returns a read\_unavailable failure.
A repeated successful headless credential issuance returns credential=null with its recorded issuance state. It never reveals the prior secret. Deliberate replacement is necessary if the secret was lost.
Handle idempotency\_conflict and target\_changed as conflicts requiring inspection. authority\_revoked and operation\_not\_permitted deny execution; capability\_unavailable and read\_unavailable are availability failures. Do not convert a retry, approval or missing response into deployment success.
## Expected result
Requests remain bound to the owner-consented resource/action grant. Operation acceptance does not establish successful execution.
## Related guides
Find the actions available to your agent and resolve access or configuration requirements.
Connect an external client, choose its access and inspect its work in StackShift.
Understand selected resources, permitted actions, owner decisions and revocation.
Follow governed resource creation, private database binding and evidence-based deployment verification.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.