Authentication

Every request to the GoOmni API is authenticated and org-scoped. REST endpoints authenticate with a session cookie; AI clients connect through the MCP endpoint with an access key.

Base URLs

Environment	Base URL
Production	`https://agent.goomni.ai`
Local development	`http://localhost:3000`

Which method to use

You are	Method
Calling REST endpoints (curl, Postman, your backend)	Session cookie — see below
Connecting Claude, Cursor, or ChatGPT	MCP access key at `/api/mcp`
Triggering runs from CI/CD or a webhook	Webhook key header `X-GoOmni-Key`
Using the public Test Case Generator	No auth; rate-limited

Session cookie (REST endpoints)

REST endpoints authenticate with a GoOmni session, sent as a cookie. Fetch a CSRF token, sign in once, and reuse the saved cookie on every subsequent request. This is the flow the Quickstart uses.

bash

# 1. Get a CSRF token
CSRF=$(curl -s -c cookies.txt https://agent.goomni.ai/api/auth/csrf \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['csrfToken'])")

# 2. Sign in (saves the session to cookies.txt)
curl -s -b cookies.txt -c cookies.txt \
  -X POST https://agent.goomni.ai/api/auth/callback/credentials \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "csrfToken=$CSRF&email=you@example.com&password=your-password" \
  -o /dev/null -w "Auth status: %{http_code}\n"

# 3. Call the API with the session cookie
curl -s -b cookies.txt https://agent.goomni.ai/api/pm/stories

Sign-in returns a redirect (302) and writes the session cookie. Send the request body as application/x-www-form-urlencoded and include the CSRF token; a JSON body will not work.

MCP access key (AI clients)

Claude Desktop, Cursor, and ChatGPT connect to the single MCP endpoint at /api/mcp, which exposes the GoOmni tools. Generate an access key in Settings → MCP access and pass it as a Bearer token. The MCP endpoint accepts that token and resolves it to your session server-side.

bash

curl https://agent.goomni.ai/api/mcp \
  -H "Authorization: Bearer <your-mcp-access-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Bearer scheme is for the /api/mcp endpoint only. SendingAuthorization: Bearer to other REST endpoints does not authenticate them — use the session cookie above. See AI Integrations for client setup.

Webhook key (CI/CD & machine-to-machine)

Endpoints that are triggered by external systems rather than a signed-in user — for example the CI/CD test trigger at /api/qa/webhooks — authenticate with a static key in the X-GoOmni-Key header instead of a session.

bash

curl -X POST https://agent.goomni.ai/api/qa/webhooks \
  -H "X-GoOmni-Key: <your-webhook-key>" \
  -H "Content-Type: application/json" \
  -d '{ "event": "run_suite", "projectId": "<uuid>" }'

Organization scoping

Every resource belongs to an organization (the top-level tenant), and most resources live under a project within it. Many endpoints therefore require an organizationId and/or projectId in the path, query, or body. Your session only grants access to organizations you are a member of.

Unauthorized requests

Missing or invalid credentials return 401; a valid identity without access to the requested organization returns 403. Both use the standard error shape; see Errors.

Public, no-auth endpoints exist for the Test Case Generator lead-gen surface (/api/public/*). Those are rate-limited instead; see Rate limits.

Standalone API keys are on the roadmap. Today, programmatic REST access uses the session-cookie flow above. If you need long-lived keys for server-to-server REST calls, contact the GoOmni team for early access.