> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitzli.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# BYOK integration boundaries

> Keep provider connections in Core and use the currently exposed automation contract.

Core owns customer provider connections and encrypted credentials in its existing database on Neon. Plugin images, build pods and public API results do not receive those credentials. Connecting a provider does not grant unrestricted access to its cloud account.

## Neon connections

The supported default is a Neon API key entered in the protected Console connection form. Use a least-privilege project key with its exact Neon project ID when possible; account/organization keys can expose paged project inventory within their scope.

Customers' owners/administrators and authorized operators can manage their connections. Read-only preview can inspect safe connection metadata but cannot connect, disconnect or enumerate management inventory. Connect and disconnect use current revisions and stable idempotency keys. Disconnect removes the stored credential while retaining revision history; it does not revoke the provider key or delete Neon data.

Local Neon CLI authorization is an optional way for the customer to create a suitable project key. Its personal OAuth flow is not Spitzli Cloud's hosted OAuth integration. Do not extract arbitrary credentials from CLI profiles, paste callback codes into chat or reuse Neon's public CLI client as a Spitzli callback client. Any future hosted callback requires its own registered client, state and PKCE validation.

The same-origin Console endpoint is `/api/console/byok/neon`; it accepts strict `get`, `connect`, `projects` and `disconnect` commands. It is a protected browser integration boundary, not a public token-exchange endpoint. Provider responses are reduced to safe metadata, and keys remain encrypted in Core.

## Hosting automation

Use [MCP](https://docs.spitzli.cloud/developers/mcp.md) discovery for the currently exposed Hosting tools and request `hosting:read`, adding `hosting:write` only where required. Do not assume historical `byok_*` commands remain public tools: native discovery lists the operations actually wired into the host.

Keep platform IDs as decimal strings. For workload changes, use fresh inventory and the exact resource identity/version required by the tool schema. Preserve the same idempotency key for unchanged intent and inspect the returned operation through `get_hosting_operation`. A queued response is not a completed provider change.

Current workspace, role, policy, tenant ownership and connection restrictions are checked again during execution. Uncertain provider outcomes require reconciliation before another write. Kubernetes access remains scoped to enrolled clusters/namespaces; Vercel and Mail remain bound to their configured account/project/connection.

Source: Core provider connections (`crates/provider-connections`), Neon Console route (`crates/control-plane/src/neon_connections.rs`) and native Hosting resource tools (`crates/control-plane/src/resource_hosting.rs`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.