Authentication

MindGraph accepts organization API keys for programmatic access and user JWTs for signed-in dashboard requests.

API Keys

Create an API key from Settings → API Keys and pass it as a Bearer token in the Authorization header.

curl -X GET https://api.mindgraph.cloud/stats \
  -H "Authorization: Bearer mg_your_api_key"

In the SDKs:

const graph = new MindGraph({
  baseUrl: "https://api.mindgraph.cloud",
  apiKey: "mg_...",
})

Warning:Keep your API keys secret. Never commit them to version control or expose them in client-side code. Use environment variables instead.

A user JWT represents a signed-in human and can call management APIs for account, membership, billing, access grants, governance, MCP custody, approvals, and Knowledge Health. Obtain one by signing in through the dashboard or through the public auth endpoints:

# Sign in
curl -X POST https://api.mindgraph.cloud/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

# Response includes access_token, refresh_token, and expires_in.
# Renew the user session:
curl -X POST https://api.mindgraph.cloud/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"your-refresh-token"}'

Send the returned access_token as a Bearer token. Role checks still apply: possessing a user JWT does not make the user an organization owner or admin.

Warning:User JWTs and refresh tokens are interactive-user credentials. Store refresh tokens as secrets and do not use a human login as a long-lived service identity. Use an organization or agent-bound API key for headless integrations.

Dashboard sessions

The dashboard uses the same signed-in user JWT. Human administrative actions such as managing members, Space and Project grants, MCP credentials, and approvals require a user session with the appropriate organization role. An API key cannot impersonate a dashboard owner or admin for those credential-custody actions.

Principal identity

The server resolves the acting human or agent from the credential and records that identity in provenance and audit data. Request fields such as agent_id do not let a caller assume another principal's authority.

An API key may be bound to a managed agent when it is created. Bound keys inherit that agent's Space, Project, tool, and governance constraints.

Note:Authorization is evaluated on each request. Revoking a key or grant affects subsequent requests, including requests from an already-open agent session.

Organization Scoping

Each API key is scoped to an organization. When you authenticate with an API key, all graph operations start within that organization's graph, then apply the credential's Space and Project grants. An organization is automatically created when you sign up.