Auth in the Marketplace¶

Authentication in Cohesity Marketplace apps has two distinct layers: platform-level authentication (handled by the Marketplace) and Gaia API authentication (handled by your application). This page explains both layers and how to configure them correctly.

The Two Auth Layers¶

Request from User / MCP Client
        │
        ▼
┌──────────────────────────────────────────┐
│  Layer 1: Cohesity Token Gate            │
│  (Marketplace platform authentication)   │
│                                          │
│  Validates Cohesity user session token.  │
│  Rejects unauthenticated requests.       │
│  Passes validated requests to app.       │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│  Your Application                        │
│                                          │
│  Layer 2: Gaia API Authentication        │
│  GAIA_API_KEY (from appspec.yaml env)    │
│  Used to call Gaia on behalf of users.   │
└──────────────────────────────────────────┘
                   │
                   ▼
         Gaia API (Helios)

Layer 1: The Cohesity Token Gate¶

The token gate is enabled by adding cohesityTag: ui to a Service port in your appspec.yaml. When enabled:

• The Marketplace enforces that every request carries a valid Cohesity session token.
• Unauthenticated users are redirected to the Cohesity login page.
• Users who are already logged in to the cluster see the app launch without friction.

# appspec.yaml — token gate ENABLED (default for web apps)
spec:
  ports:
    - port: 8080
      cohesityTag: ui     # Token gate is ON

Bypassing the Token Gate¶

Set unrestricted_app_ui_access: true in app.json to bypass the token gate:

{
  "unrestricted_app_ui_access": true
}

Use this only when clients connect programmatically and cannot complete a browser-based login flow — for example, an MCP server that Cursor and Claude Desktop connect to directly.

When the token gate is bypassed, your application is responsible for any access control. See MCP Server Auth below.

Layer 2: Gaia API Authentication¶

Your application calls the Gaia API using an API key. In Marketplace deployments, the API key is configured by the cluster admin in appspec.yaml and injected into the container as an environment variable.

# appspec.yaml
env:
  - name: GAIA_API_KEY
    value: "YOUR_GAIA_API_KEY"    # Admin sets this before uploading

# Your application reads it from the environment
import os
gaia_api_key = os.environ["GAIA_API_KEY"]

The API key is never sent to the frontend. It stays in the container environment and is used exclusively for server-side Gaia API calls.

Web App Auth Pattern (Example 05)¶

For browser-based apps, the token gate handles user authentication. Your app uses the configured API key for all Gaia calls on behalf of every user.

User Browser
    │  Cohesity session cookie
    ▼
Token Gate  ──── validates ──────────────────────────────────┐
    │                                                         │
    ▼  (passes through)                                       │
Your FastAPI App                                             │
    │  GAIA_API_KEY (from env)                               │
    ▼                                                         │
Gaia API  ◄────────────────────────────────────────────────┘

This means all authenticated users share the same Gaia API key. The Gaia API key controls which datasets are accessible — choose a key that provides appropriate access for the app's user base.

Reading Auth Token in Your App (Optional)¶

If you need to verify that your app is running in the Marketplace (not a local dev environment), check for APP_AUTHENTICATION_TOKEN:

import os

def is_running_in_marketplace() -> bool:
    return bool(os.getenv("APP_AUTHENTICATION_TOKEN"))

This token is a short-lived credential issued by the Marketplace platform. You can also use it to make calls to the Cohesity Apps API (APPS_API_ENDPOINT_IP:APPS_API_ENDPOINT_PORT) if your app needs to interact with cluster resources.

MCP Server Auth Pattern (Example 06)¶

MCP clients (Cursor, Claude Desktop, custom agents) connect programmatically without a browser. They cannot complete a Cohesity SSO login flow.

The solution: disable the token gate (unrestricted_app_ui_access: true) and rely on the Gaia API key as the only auth mechanism.

MCP Client (Cursor / Claude Desktop)
    │  HTTP POST /mcp  (no browser session)
    ▼
(No token gate — unrestricted_app_ui_access: true)
    │
    ▼
FastMCP Server (in container)
    │  GAIA_API_KEY (from appspec.yaml env)
    ▼
Gaia API

Security considerations: - The MCP endpoint is accessible to anyone who can reach the NodePort on the cluster network. - Use network policies or VPN to restrict which clients can reach the NodePort. - The Gaia API key should be scoped to allow access only to the datasets the MCP server should expose. - Rotate the API key periodically; update it in appspec.yaml and redeploy.

Future: OAuth2¶

The Gaia API will support OAuth2 in a future release. When available, the MCP server will be able to: - Delegate authentication to the user's Cohesity identity. - Apply per-user dataset access controls. - Support proper token revocation.

The current apiKey pattern is a stepping stone. The application structure in Example 06 is designed to make this migration straightforward when OAuth2 is available.

Summary: Which Pattern to Use¶

Next Steps¶

• Packaging a Gaia App — Build and bundle your app
• MCP Server on the Marketplace — Full walkthrough for Example 06
• AppSpec Reference — Complete field reference