Authentication

Igris supports several authentication methods depending on the context.

Session Cookies (Dashboard)

When you log in through the dashboard, Better Auth sets a session cookie. The cookie name depends on the environment:

Production: __Secure-igris.session_token (Secure flag set, HTTPS only)
Development: igris.session_token

This cookie is automatically sent with all dashboard requests. For API calls from a browser context, include credentials:

fetch("https://api.igrisecurity.com/api/v1/policies", {
  credentials: "include" // sends session cookie
});

Or pass the cookie explicitly:

curl https://api.igrisecurity.com/api/v1/policies \
  -H "Cookie: __Secure-igris.session_token=eyJhbGciOi..."

OAuth (GitHub / Google)

GitHub and Google OAuth are conditionally enabled based on server configuration. When the relevant environment variables are set (GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET or GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET), the corresponding social login buttons appear on the sign-in page. OAuth sessions are issued as session cookies identical to email/password login — no additional API changes are needed.

API Keys (Programmatic Access)

For MCP proxy connections and CI/CD integrations, use API keys.

Creating an API Key

Go to Settings → API Keys in the dashboard
Click Create Key
Give it a label (e.g., “Proxy - Production”, “CI Pipeline”)
Copy the key — it’s only shown once

API keys follow the format ig_ followed by 48 lowercase hex characters (24 random bytes), for a total of 51 characters:

ig_a3f82c1d9e4b7f0612a5c8e3d1f29b047e6a8c2d5f1b4e7a

Using an API Key

Pass the key in the Authorization header:

curl https://api.igrisecurity.com/api/v1/policies \
  -H "Authorization: Bearer ig_a3f82c1d9e4b7f06..."

Key Scoping and Permissions

API keys are read-only by default. GET and HEAD requests succeed with a valid key. Write operations (POST, PUT, PATCH, DELETE) on management API routes require a session cookie — requests made with an API key alone will receive 403 Forbidden on those routes. Keys are scoped to the organization they were created in.

Revoking Keys

Revoke a key in Settings → API Keys by clicking Revoke. Revoked keys immediately stop working — any proxy connections using that key will receive 401 Unauthorized.

Ingest API Authentication

The Ingest API (/api/v1/ingest/*) uses a separate BetterAuth API-key system. These keys are issued for log ingestion from external proxies (Portkey, Helicone, Cloudflare integrations) and are distinct from the management API keys described above. Pass them the same way — Authorization: Bearer <key> — but generate them from the Ingest settings, not the main API Keys page.

MCP Gateway and LLM Gateway Authentication

The MCP gateway (/v1/mcp/:slug) and LLM gateway (/llm/:slug/*) use Bearer API key only. Session cookies are not accepted on these routes.

CORS: Both routes allow wildcard origins (*) — designed for programmatic clients and browser-based SDKs calling from any origin.
No session cookie fallback: There is no session-cookie auth path on gateway routes; the Bearer key is the only accepted credential.

# MCP gateway
curl https://api.igrisecurity.com/v1/mcp/my-server \
  -H "Authorization: Bearer ig_a3f82c1d9e4b7f06..."

# LLM gateway
curl https://api.igrisecurity.com/llm/openai/v1/chat/completions \
  -H "Authorization: Bearer ig_a3f82c1d9e4b7f06..."

Organization Context

All API requests are scoped to an organization. The organization is determined by:

Session cookies — the user’s active organization in their session
API keys — the organization the key was created in

Error Responses

Status	Meaning
`401 Unauthorized`	Missing, invalid, or revoked credentials
`403 Forbidden`	Valid credentials but insufficient role permissions
`403 Forbidden` (plan)	Feature requires a higher plan tier

A 401 response body contains only an error field:

{
  "error": "Invalid or expired API key"
}

A plan-gated 403 response includes additional context:

{
  "error": "Feature not available on your plan",
  "feature": "hipaa",
  "currentPlan": "starter",
  "requiredPlan": "scale"
}

RBAC Roles

Permissions are enforced based on the user’s role in the organization:

Role	Policies	Sessions	Servers	API Keys	Compliance	Billing	Members
Owner	Full	Full	Full	Full	Full	Full	Full
Admin	Full	Full	Full	Full	Full	—	Manage
Developer	Read/Write	Read/Write	Read/Write	Read/Write	—	—	—
CISO	Read/Write	Read/Write	Read	—	Read/Write	—	—
Auditor	Read	Read	Read	—	Read	—	—

​Authentication

​Session Cookies (Dashboard)

​OAuth (GitHub / Google)

​API Keys (Programmatic Access)

​Creating an API Key

​Using an API Key

​Key Scoping and Permissions

​Revoking Keys

​Ingest API Authentication

​MCP Gateway and LLM Gateway Authentication

​Organization Context

​Error Responses

​RBAC Roles