Authentication

infrastrActure uses API keys with instance binding and tier-based access control. The key is the security boundary. Clients do not get to choose their own tier.

Model

API Key Format

mcp_sk_<64-hex-characters>

stored hashed in PostgreSQL
plaintext is only shown once when generated
tied to one instanceId

Passing the Key

Either header is accepted:

Authorization: Bearer mcp_sk_...

X-API-Key: mcp_sk_...

Request Lifecycle

Every authenticated request goes through the same gate:

Both the instance binding and the tier check happen on the server. Clients cannot smuggle a tier upgrade through headers or request bodies.

Instance Binding

Every key is bound to a single instance. Requests are validated against that binding.

That means a key minted for one instance (e.g. chat-app-dev) cannot be replayed against another (e.g. chat-app-prod), even if both belong to the same client team.

Access Tiers

Tier	Purpose	What It Can See
`standard`	normal application runtime	user installations, standard shared tools, sandboxes
`admin`	platform control plane	everything in `standard`, plus admin shared tools, built-in `infrastrActure` MCP server, infra SSH

Standard vs Admin Exposure

Shared Tool Semantics

Examples from the current implementation:

Shared Tool	Tier
`google-workspace`	`standard`
`infAct Browser` (`browser-use`)	`standard`
`github-mcp-cloud`	`admin`
`livekit-docs`	`admin`
`linkedin-mcp`	`admin`

This is how the platform keeps org-scoped shared GitHub access away from normal users while still allowing user-safe shared tools.

Per-environment key pattern

A client that serves both end users and operators should hold one key per tier and pick which one to use per outbound call. The naming is a convention; what matters is that one key per tier is bound to the right instance.

Env var	Use
`INFRASTRACTURE_API_KEY_STANDARD`	normal user sync and standard shared-tool access
`INFRASTRACTURE_API_KEY_ADMIN`	admin controls, shared admin tools, Infra SSH

App-layer filtering inside the client is not enough on its own. The upstream key tier must match the caller's privilege.

Identity Headers

For user-scoped operations, include:

Header	Purpose
`X-User-Id`	user identity for OAuth, sandbox, and infra SSH operations
`X-Request-Id`	optional trace correlation

Unauthenticated Endpoints

Only a small surface is open:

Endpoint	Reason
`/health`	liveness check
`/api/auth/callback`	OAuth completion path

Infra SSH

See Infra SSH / Security Model for the dedicated boundary model.

Infra SSH adds a second gate:

request must arrive with an admin-tier API key
privileged mutations require a short-lived approval lease

That means “has admin key” and “has active elevated session” are separate checks.

Operational Guidance

default every new key to standard
mint admin keys only for trusted control-plane clients
never let a user-facing client use an admin key for ordinary sync
rotate keys when roles or deployments change