Merge remote-tracking branch 'origin/staging' into feat/v2-execute-version-pin-paused-detail

Author: waleedlatif1

apps/docs/content/docs/api-reference/authentication.mdx

@@ -24,7 +24,7 @@ Workspace Admins can turn off **Allow personal API keys**. The workspace policy
 ## Create and store a key [#generating-api-keys]
 
 1. Open **Account settings → Sim API keys** to create a personal key, or **Workspace settings → Sim API keys** to create a workspace key.
-2. Select **Create API key**, enter a name, and create it. Workspace-key creation requires workspace **Admin** access and the applicable key-management permission.
+2. Select **Create API key** and enter a name. Choose its **Access** and when it **Expires**, then create it. Workspace-key creation requires workspace **Admin** access and the applicable key-management permission.
 3. Copy the key and store it in a server-side environment variable such as `SIM_API_KEY`.
 
 <Callout type="warn">
@@ -33,6 +33,23 @@ Sim shows the complete key once, immediately after creation. Copy it before clos
 
 Delete a key from the same settings page to revoke it. Update applications that used it with a replacement key.
 
+### Access [#key-access]
+
+| Access | Allows |
+| --- | --- |
+| **Full access** | Everything the key's identity can do: reads, changes, deploys, and workflow runs |
+| **Read only** | The operations the [`api:read` scope](#oauth-access-tokens) allows, including searches sent as POST requests and search chat |
+
+A read-only key cannot change workspace resources or run, resume, or cancel workflows. Reads can still cost credits: searches use embedding credits, and search chat uses model credits and keeps a private conversation history. Selector lookups call third-party services with your connected accounts.
+
+A refused request fails with `403` and the message `This API key is read-only and cannot perform this operation`. Where the surface carries a code, it is `READ_ONLY_API_KEY`: in `error.details.code` on the v2 API and the Sim MCP server, in `details.code` on the v1 API and workflow execution, and in `error.data.code` on a workflow MCP server.
+
+Access narrows a key; it never grants more than the key's identity already has. Access is fixed at creation, so create a new key to change it. Keys created before access levels existed have full access. Keys created from the deploy modal or for a workflow MCP server always have full access, because they exist to run workflows. If **Access** isn't shown when you create a key, read-only keys aren't available on your deployment yet.
+
+### Expiration [#key-expiration]
+
+A key expires 30 days, 90 days, or 1 year after creation, or never. The settings page defaults to never. After it expires, every request with the key fails with `401`. The v1 and v2 APIs, both MCP servers, and workflow execution answer with the message `API key has expired`. Create a replacement before then. The key list shows each key's expiration date. `GET /api/v2/meta` reports the calling key's `expiresAt` and `scopes`.
+
 ## Send an API key [#using-api-keys]
 
 Send the key in `X-API-Key`. The v2 API accepts `Authorization: Bearer` only for [OAuth access tokens](#oauth-access-tokens), not API keys. For example, with `SIM_API_KEY` and `WORKFLOW_ID` set:

apps/docs/content/docs/cli/authentication.mdx

@@ -154,7 +154,7 @@ export SIM_WORKSPACE="2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67"
 sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' --output json
 ```
 
-The environment key overrides stored authentication. Use a workspace key only for supported workspace-scoped operations; organization audit logs and fork administration require a personal credential. Never commit credentials. `SIM_CONFIG_DIR` relocates local state when a runner has no writable home directory.
+The environment key overrides stored authentication. Use a workspace key only for supported workspace-scoped operations; organization audit logs and fork administration require a personal credential. A job that runs workflows needs a **Full access** key; a **Read only** key suits jobs that only read, such as exporting logs. Choose an expiration your secret rotation covers: an expired key fails with `401` and `API key has expired`. See [key access and expiration](/api-reference/authentication#key-access). Never commit credentials. `SIM_CONFIG_DIR` relocates local state when a runner has no writable home directory.
 
 ### GitHub Actions
 

apps/docs/content/docs/mcp/authentication.mdx

@@ -55,8 +55,10 @@ A personal key uses your current access in the workspaces you can reach. A works
 
 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.
 
+For an agent that only reads, create a **Read only** key: it reaches the operations `api:read` allows, and a tool call that changes something or runs a workflow fails with `403` and the code `READ_ONLY_API_KEY`. Search and search chat still use credits. See [key access](/api-reference/authentication#key-access).
+
 <Callout type="warn">
-  Keys created in Sim settings have no default expiration. Revoke a key when it is no longer needed. Prefer OAuth for an app that
+  Keys created in Sim settings never expire unless you choose an 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.
 </Callout>

apps/docs/openapi-v2-billing.json

@@ -566,6 +566,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",

apps/docs/openapi-v2-files-audit.json

@@ -4713,6 +4713,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",

apps/docs/openapi-v2-knowledge.json

@@ -6018,6 +6018,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",

apps/docs/openapi-v2-logs.json

@@ -1065,6 +1065,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",

apps/docs/openapi-v2-resources.json

@@ -4947,7 +4947,7 @@
       "get": {
         "operationId": "getApiMeta",
         "summary": "Get API status",
-        "description": "Get the calling credential’s type and expiry. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate resource permissions.\n\nOAuth scope: `api:read`.",
+        "description": "Get the calling credential’s type, expiry, and API scopes. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate resource permissions.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "meta.capabilities.read",
         "x-oauth-scope": "api:read",
         "tags": ["Meta"],
@@ -4985,7 +4985,8 @@
                       "data": {
                         "v2Enabled": true,
                         "keyType": "personal",
-                        "expiresAt": null
+                        "expiresAt": null,
+                        "scopes": ["api:read", "api:write"]
                       }
                     }
                   }
@@ -14807,6 +14808,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",
@@ -18642,9 +18644,17 @@
               }
             ],
             "description": "ISO 8601 timestamp when the calling credential expires, or null when it does not."
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["api:read", "api:write", "search:read"]
+            },
+            "description": "API scopes the calling credential holds. A read-only API key holds only api:read: it is refused every operation that changes state and every operation that declares no API scope, so api:read alone does not authorize those. A full-access key holds api:read and api:write; an OAuth access token holds what it was granted."
           }
         },
-        "required": ["v2Enabled", "keyType", "expiresAt"],
+        "required": ["v2Enabled", "keyType", "expiresAt", "scopes"],
         "additionalProperties": false,
         "title": "API status",
         "description": "API availability and lifecycle facts about the calling credential."
@@ -18660,13 +18670,14 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "API status response",
-        "description": "API availability, credential type, and expiry for the caller.",
+        "description": "API availability, credential type, expiry, and scopes for the caller.",
         "examples": [
           {
             "data": {
               "v2Enabled": true,
               "keyType": "personal",
-              "expiresAt": null
+              "expiresAt": null,
+              "scopes": ["api:read", "api:write"]
             }
           }
         ]

apps/docs/openapi-v2-tables.json

@@ -5977,6 +5977,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",

apps/docs/openapi-v2-workflows.json

@@ -7785,6 +7785,7 @@
           "PERMISSION_GROUP_CAPABILITY_BLOCKED",
           "INTEGRATION_NOT_ALLOWED",
           "INSUFFICIENT_SCOPE",
+          "READ_ONLY_API_KEY",
           "SCIM_MANAGED_MEMBERSHIP"
         ],
         "title": "Forbidden detail code",