Authentication

Use OAuth for an app that supports browser sign-in. Use an API key for a client that needs a fixed credential. Both remain subject to the credential's current resource access and operation permissions.

OAuth

On first connection, your app opens Sim in the browser. Sign in and review the requested access before approving it. The app stores a one-hour access token, so you do not copy a secret. With offline_access, it can refresh access for up to 30 days from the initial grant; after that, sign in again. Refreshing does not extend that fixed lifetime.

The approval screen names the app and what it can do:

For reads only, configure the app to request api:read; changes then fail with an insufficient-scope error. A token's scope does not grant a workspace role or bypass resource permissions.

Tokens are issued for the Sim MCP server itself. An app cannot take one to another service and use it there.

Revoke access

Open Settings → General → Authorized apps in Sim, find the app, and revoke it. The app's next request fails, and you can reconnect at any time. Revoking does not undo changes the app already made.

API keys

Apps that cannot sign in through a browser, such as CI jobs and headless agents, can send a Sim API key in the X-API-Key header, or as Authorization: Bearer <key>.

claude mcp add --transport http sim https://mcp.sim.ai/mcp \
  --header "X-API-Key: $SIM_API_KEY"

{
  "mcpServers": {
    "sim": {
      "url": "https://mcp.sim.ai/mcp",
      "headers": { "X-API-Key": "${env:SIM_API_KEY}" }
    }
  }
}

A personal key uses your current access in the workspaces you can reach. A workspace key reaches only its own workspace and follows workspace-key operation and role policies rather than its creator's human permission group. Some operations refuse workspace keys; search_operations marks them personalCredentialOnly.

The Cursor process must receive SIM_API_KEY for its environment interpolation to work. For a self-hosted deployment, replace the Cloud URL in both examples with your server URL.

Organization policy

Organization policy can restrict personal credentials in affected workspaces. The Personal API Keys policy applies to personal API-key and OAuth requests; OAuth requests also require OAuth App Access. OAuth approval and refresh remain subject to organization policy. See Permission groups for policy resolution.

Related docs

• Connect an app for server URLs and client configuration
• API authentication for key creation and credential scope
• Tools for read and write operation behavior