ConceptsAuthentication And Tokens

Authentication And Tokens

Gestalt has three separate credential layers:

  • platform auth for the human caller of the server
  • integration auth for outbound calls to upstream systems
  • API tokens for programmatic access to Gestalt itself

Platform Auth

Platform auth is configured under auth.

auth:
  provider: oidc
  config:
    issuer_url: https://login.example.com
    client_id: ${OIDC_CLIENT_ID}
    client_secret: ${OIDC_CLIENT_SECRET}

Built-in platform auth providers are:

  • none
  • local
  • google
  • oidc

The platform auth provider controls login to the UI, authenticated HTTP routes, and /mcp.

Integration Auth

Integration auth lives inside providers.*.connections.

Examples:

  • type: none for public spec-backed surfaces that use a mode: none connection
  • type: oauth2 for user-scoped or shared OAuth flows
  • type: manual or type: bearer for manually entered credentials
  • type: mcp_oauth for upstream MCP servers that implement MCP OAuth

OAuth connections are started through POST /api/v1/auth/start-oauth and completed by GET /api/v1/auth/callback.

Manual connections are created through POST /api/v1/auth/connect-manual.

Stored Connections

Gestalt stores integration credentials by:

  • user
  • integration
  • connection name
  • instance

This lets one user keep multiple instances of the same integration, such as:

  • separate Jira sites
  • different tenant parameters
  • multiple named auth flows on one integration

API Tokens

API tokens authenticate callers to Gestalt itself.

Create them with:

gestalt tokens create --name automation

Or through the HTTP API:

POST /api/v1/tokens
Authorization: Bearer <session-or-api-token>
Content-Type: application/json

They can be scoped to specific integrations and are accepted through:

  • Authorization: Bearer gst_api_...
  • the gestalt client CLI
  • authenticated calls to /mcp

server.api_token_ttl controls the token lifetime.

Session Cookies

When platform auth is enabled, the browser session is stored in a session_token cookie.

  • Cookies are HttpOnly.
  • Cookies use SameSite=Lax.
  • Cookies are marked Secure when server.base_url uses https://.

Choosing An Auth Strategy

  • Use auth.provider: none for local development and trusted internal environments.
  • Use local for a single-user dev server that still exercises login flows.
  • Use google or oidc for normal multi-user deployments.
  • Use OAuth integration auth when each user should bring their own account.
  • Use identity mode when the server should call upstreams with one shared service credential.
IntegrationsMCP