# Cohesivity auth.md

Cohesivity is an agent-native infrastructure API. Guest registration creates an ephemeral tenant; account-authorized creation atomically creates an owned claimed tenant with no expiry. Tenant registration is separate from OAuth client registration.

## Register an agent project

Prefer the local MCP `create_tenant` tool, which runs the full quickstart flow including client integrations and project guidance. Without a Cohesivity MCP, use the version-pinned installer in `https://cohesivity.ai/skill.md`; without Node, use `curl -fsSL https://cohesivity.ai/quickstart.sh | bash`. Plain guest quickstart performs `POST https://cohesivity.ai/api/genesis` and writes credentials to a gitignored `.cohesivity`. Account-authenticated local bootstrap instead uses the private `POST https://cohesivity.ai/api/mcp/bootstrap` file API with an OAuth account token, `confirmed: true`, and an idempotency key. It stores the attachment locally without printing it. These supported paths carry bootstrap attribution and idempotency; do not hand-roll tenant creation. A genesis call sending a `User-Agent` containing `curl` is rejected with `403 bannedUserAgent`. Reuse a valid `.cohesivity`; never silently reassign its tenant after login.

Guest tenants expire after 72 hours unless a human approves the claim flow. Use `claim_tenant` with `confirmed: true` after explicit approval and share only the returned approval URL. Internally it uses `POST https://cohesivity.ai/api/claim/url`; its wait capability uses `GET https://cohesivity.ai/api/wait` and never enters MCP output. Account-created tenants are already claimed.

## Credential types

- `coh_man_...`: tenant management key. Send it as `Authorization: Bearer <coh_man_...>` to `/api/*` management endpoints.
- `coh_app_...`: tenant application key. Use it only with `/edge/*` offering endpoints as documented by the selected offering.
- Wait tokens and edge session tokens: narrow, short-lived credentials returned by the operation that creates them.

Keep credentials agent-side in `.cohesivity`. Do not put them in browser bundles, source control, logs, chat, URLs beyond the documented application-key contract, or third-party registration forms.

## Hosted MCP

One hosted MCP server at `POST https://cohesivity.ai/mcp` serves documentation and management. It accepts initialize, ping, tools/list, and tools/call without an Authorization header. `get_cohesivity_documentation` is read-only and needs no tenant, credentials, confirmation, or OAuth scope. The former `https://cohesivity.ai/mcp/manage` endpoint is retired and returns HTTP 410; reconfigure clients to `https://cohesivity.ai/mcp`. Public connection and creation need no guest identity, token, session, browser consent, or auth setup. Public `create_tenant` takes only `{confirmed: true}`; each call creates a new rate-limited 72-hour ephemeral tenant. There is no `idempotency_key` in public creation, so unauthenticated callers cannot replay another caller's credentials. Do not automatically retry an ambiguous creation outcome. Reuse an existing `.cohesivity` instead of creating another tenant. Public creation returns no browser download URL.

Hosted public `claim_tenant`, `tenant_status`, `provision_resource`, and `give_feedback` each require an explicit `tenant_id` and its secret `coh_management_key` from `.cohesivity` in the arguments. The key is marked `writeOnly` in the input schema and verified against the tenant ID and current tenant state; it is never logged or returned by follow-up tools. Do not use the Authorization header for tenant keys on this MCP endpoint; that header selects OAuth. Public connection does not mean tenant operations are unauthenticated. Application keys are not accepted.

Hosted `create_tenant` returns project metadata plus `credentials_file: { filename: ".cohesivity", content: "<exact .cohesivity file contents>" }` in `structuredContent` and the compatible text result. This deliberate secret-bearing result and key-bearing tool inputs may enter model or client retained tool history. Write `credentials_file.content` verbatim to `.cohesivity` in the current project with mode `0600`, and gitignore it. Never overwrite a different existing tenant or print credentials in chat, logs, or source, and never commit them. If you cannot write the file safely, report that explicitly; the server cannot force a client filesystem write. Local MCP output remains metadata-only.

## Optional account OAuth

Account sign-in is an explicit choice through the client's OAuth login command or UI, when supported; public connection does not require it. OAuth 2.1 uses authorization code flow with mandatory PKCE S256, exact registered redirects, RFC 8707 resource binding, one-use approval state, and explicit consent. New OAuth sign-in uses an existing account session or redirects to Google account sign-in when no account cookie exists. Explicit `guest=true` is legacy compatibility only; existing guest tokens still work. Invalid Authorization returns HTTP 401 and must never fall back to public access or downgrade to guest. The OAuth resource is `https://cohesivity.ai/mcp`. Tokens issued for the retired `/mcp/manage` resource are rejected rather than rewritten, so clients that signed in before the move must sign in again; tenant `.cohesivity` files are unaffected. Signing in never reassigns an existing tenant.

Authorization works before the account owns a tenant. Account OAuth links directly to the Cohesivity account without tenant selection. OAuth tenant tools require an explicit `tenant_id`, retain their existing scopes, and run a fresh claimed-ownership or ephemeral-creation check on every call; they do not take management keys in arguments. Guests can access only still-ephemeral tenants created by the same legacy guest. OAuth `create_tenant` requires `idempotency_key` and `mcp:tenants:create`; authorized retries with the same key reuse the creation. Account creation atomically creates an owned claimed tenant with no expiry. After a legacy guest tenant is claimed, reconnect with the owning account for OAuth access; a guest grant never becomes an account grant.

Only OAuth creation offers the non-secret `credentials_download_url` at `https://cohesivity.ai/mcp/tenants/:tenant_id/credentials` as an optional fallback for clients with no writable workspace, not a prerequisite for coding clients. Download requires the legacy consent browser guest cookie for its still-ephemeral tenant, or an account browser session that owns the claimed tenant. The URL alone and an MCP OAuth bearer cannot download the file. Keep the private attachment out of chat and apply the same file safeguards.

A temporary authentication database or abuse-control outage returns HTTP 503; retry an OAuth authentication failure with the existing token without signing in again. Do not automatically retry public creation when its outcome is ambiguous. Invalid or expired tokens still return HTTP 401.

The local `cohesivity-local` server reads the project root's `.cohesivity` credentials privately without login. Optional CLI account sign-in uses `node <installed-plugin>/mcp/project-bootstrap.mjs login`; `node <installed-plugin>/mcp/project-bootstrap.mjs logout` removes local account auth. Replace `<installed-plugin>` with the installed plugin directory. The private account auth store lives outside the project; account login makes new tenants account-owned, while existing `.cohesivity` credentials are reused. The hosted server never reads local project files.

Discovery is standards-based: Protected Resource Metadata is at `https://cohesivity.ai/.well-known/oauth-protected-resource/mcp`; Authorization Server Metadata is at `https://cohesivity.ai/.well-known/oauth-authorization-server`; public clients register through `https://cohesivity.ai/oauth/register`. Access tokens are short-lived and refresh tokens rotate; revocation is at `https://cohesivity.ai/oauth/revoke`. There is no client_credentials or custom headless grant.

The optional OAuth scopes are `mcp:tenants:create`, `mcp:tenant:read`, `mcp:resources:write`, `mcp:feedback:write`.

The server exposes exactly six tools: `get_cohesivity_documentation` plus the five management tools `create_tenant`, `claim_tenant`, `tenant_status`, `provision_resource`, and `give_feedback`. OAuth tokens always list the documentation tool and list each management tool only when its scope is granted. The provisioning tool accepts single `resource`/`configuration` or bulk `resources`/`configurations`. `create_tenant`, `claim_tenant`, and `provision_resource` require `confirmed: true`, sent only when the current user request explicitly authorizes that exact action. No other control-plane tools, operation handles, or `/edge/*` operations are exposed.

`give_feedback`: Submit feedback on Cohesivity and its services anytime; no user confirmation is needed. Exclude personal information and secrets. It requires existing tenant context: local inputs are `project_root` and `feedback`; hosted public inputs are `tenant_id`, `coh_management_key`, and `feedback`; OAuth inputs omit the management key. Send nonempty, trimmed text of at most 20,000 characters; do not collect personal data, conversation context, or files. It takes no `confirmed` or `requiresUserInteraction` field. OAuth calls require `mcp:feedback:write`; existing OAuth connections must reconnect to grant it. The tool uses `POST /api/feedback/service` with existing tenant authentication, works while paused, and appends each submission without minting or redeeming discount tokens or changing billing. It returns only `{success:true}`, with no discount tokens, instructions, or feedback echo. User-authorized discount reports still use the documented `/api/feedback` HTTP flow, not this tool. There is no no-tenant feedback path.

Hosted `create_tenant` is the sole exception to tenant-key exclusion from MCP results. Other outputs are projected through fixed allowlists and recursively scrubbed. `claim_tenant` returns only the human approval URL; raw wait capabilities, OAuth bearers, provider secrets, and raw logs never cross the result boundary. OAuth storage retains client metadata, exact redirect URIs, approved scopes, one-way SHA-256 token hashes, and hashed creation idempotency keys; legacy guest identities and browser credential hashes remain for compatibility. Public access creates none of those OAuth records. The Google OAuth routes under `/edge/auth/<tenant>/...` remain unrelated tenant-application social login.

Full authentication and endpoint documentation: https://cohesivity.ai/docs and https://cohesivity.ai/skill.md