# Authentication (/mcp/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 \[#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:

| Access | Scope | Allows |
| - | - | - |
| Read-only | `api:read` | Reading workspaces, workflows, runs, tables, files, knowledge bases, and logs |
| Full | `api:write` | Everything above, plus creating, changing, running, deploying, and deleting |

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 \[#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 \[#api-keys]

Apps that cannot sign in through a browser, such as CI jobs and headless
agents, can send a Sim [API key](/api-reference/authentication) in the
`X-API-Key` header, or as `Authorization: Bearer <key>`.

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

```json title="~/.cursor/mcp.json"
{
  "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.

Warning:

Keys created in Sim settings have no default expiration. Revoke a key when it is no longer needed. Prefer OAuth for an app that
supports browser sign-in, and store keys in your app's secret or environment
settings rather than in a shared config file.

## Organization policy \[#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](/platform/enterprise/access-control) for policy resolution.

## Related docs \[#related-docs]

- [Connect an app](/mcp/overview) for server URLs and client configuration
- [API authentication](/api-reference/authentication) for key creation and credential scope
- [Tools](/mcp/tools) for read and write operation behavior