# Get permission group (/api-reference/permission-groups/getPermissionGroup)

`GET /api/v2/organizations/{organizationId}/permission-groups/{groupId}`

Get a permission group and its resolved settings. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.

OAuth scope: `api:read`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:read"
      ]
    }
  ],
  "schemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
    },
    "oauthBearer": {
      "type": "oauth2",
      "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
          "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "scopes": {
            "api:read": "Read your workspaces, workflows, files, tables, and logs",
            "api:write": "Read, create, change, run, and delete resources in your workspaces",
            "offline_access": "Stay signed in without asking again"
          }
        }
      }
    }
  }
}

```

Required OAuth scope: `api:read`.

## Request examples

### cURL

```bash
curl --request GET 'https://www.sim.ai/api/v2/organizations/string/permission-groups/string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/organizations/string/permission-groups/string", {
  "method": "GET",
  "headers": {
    "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "GET",
    "https://www.sim.ai/api/v2/organizations/string/permission-groups/string",
    headers={
  "X-API-Key": "YOUR_API_KEY"
},
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

import (
  "io"
  "net/http"
  "os"
)

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/organizations/string/permission-groups/string", nil))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}
```

### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/organizations/string/permission-groups/string"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}
```

### C#

```csharp
using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/organizations/string/permission-groups/string");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Parameters

```json

[
  {
    "name": "organizationId",
    "in": "path",
    "required": true,
    "description": "Organization that owns the permission groups.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Organization that owns the permission groups."
    }
  },
  {
    "name": "groupId",
    "in": "path",
    "required": true,
    "description": "Permission group identifier.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Permission group identifier."
    }
  }
]

```

## Responses

### 200

```json

{
  "description": "The group, its resolved settings, and workspace scope.",
  "headers": {
    "X-RateLimit-Limit": {
      "description": "Maximum requests allowed in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit",
        "description": "Maximum requests allowed in the current window."
      }
    },
    "X-RateLimit-Remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit remaining",
        "description": "Requests remaining in the current window."
      }
    },
    "X-RateLimit-Reset": {
      "description": "ISO 8601 timestamp when the current rate-limit window resets.",
      "schema": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "title": "Rate limit reset",
        "description": "ISO 8601 timestamp when the current rate-limit window resets."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Permission group identifier."
              },
              "organizationId": {
                "type": "string",
                "description": "Organization that owns the group."
              },
              "name": {
                "type": "string",
                "description": "Group name, unique within the organization."
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Optional description of the group."
              },
              "config": {
                "type": "object",
                "properties": {
                  "allowedIntegrations": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none."
                  },
                  "allowedModelProviders": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Model providers are limited to this list. Null permits every value; an empty list permits none."
                  },
                  "deniedModels": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Models listed in this list are blocked."
                  },
                  "deniedTools": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Integration tools listed in this list are blocked."
                  },
                  "hideTraceSpans": {
                    "type": "boolean",
                    "description": "Withhold per-block trace spans from logs and from the API."
                  },
                  "hideKnowledgeBaseTab": {
                    "type": "boolean",
                    "description": "Revoke the Knowledge Base module. Members cannot open, search, or query any knowledge base."
                  },
                  "hideTablesTab": {
                    "type": "boolean",
                    "description": "Revoke the Tables module. Members cannot read or write any table."
                  },
                  "hideCopilot": {
                    "type": "boolean",
                    "description": "Revoke Chat. Members cannot ask Sim to build or edit anything."
                  },
                  "hideIntegrationsTab": {
                    "type": "boolean",
                    "description": "Revoke integration connections. Members cannot view, add, or remove an OAuth connection."
                  },
                  "hideSecretsTab": {
                    "type": "boolean",
                    "description": "Revoke secrets. Members cannot read, add, or change a workspace environment variable."
                  },
                  "hideApiKeysTab": {
                    "type": "boolean",
                    "description": "Revoke workspace API keys. Members cannot list, create, or revoke one."
                  },
                  "hideInboxTab": {
                    "type": "boolean",
                    "description": "Revoke the Sim Mailer inbox. Members cannot read or send mail."
                  },
                  "hideFilesTab": {
                    "type": "boolean",
                    "description": "Revoke the Files module. Members cannot list, upload, or download workspace files."
                  },
                  "disableMcpTools": {
                    "type": "boolean",
                    "description": "Block agents from calling MCP tools."
                  },
                  "disableCustomTools": {
                    "type": "boolean",
                    "description": "Block agents from calling user-defined custom tools."
                  },
                  "disableSkills": {
                    "type": "boolean",
                    "description": "Block agents from loading skills."
                  },
                  "disableInvitations": {
                    "type": "boolean",
                    "description": "Prevent inviting anyone to a workspace or to the organization."
                  },
                  "disablePublicApi": {
                    "type": "boolean",
                    "description": "Revoke public API access. Calls to a deployed workflow are refused."
                  },
                  "disablePublicFileSharing": {
                    "type": "boolean",
                    "description": "Revoke public file sharing. Members cannot create a share link."
                  },
                  "allowedFileShareAuthTypes": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "public",
                            "password",
                            "email",
                            "sso"
                          ]
                        }
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Public file-share authentication is limited to this list. Null permits every value; an empty list permits none."
                  },
                  "hideDeployApi": {
                    "type": "boolean",
                    "description": "Prevent deploying a workflow as an API endpoint."
                  },
                  "hideDeployMcp": {
                    "type": "boolean",
                    "description": "Prevent exposing a workflow as an MCP server."
                  },
                  "hideDeployChatbot": {
                    "type": "boolean",
                    "description": "Prevent deploying a workflow as a chat."
                  },
                  "allowedChatDeployAuthTypes": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "public",
                            "password",
                            "email",
                            "sso"
                          ]
                        }
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Chat deployment authentication is limited to this list. Null permits every value; an empty list permits none."
                  },
                  "disablePersonalApiKeys": {
                    "type": "boolean",
                    "description": "Prevent members from using a personal API key against this workspace."
                  },
                  "disableLogExport": {
                    "type": "boolean",
                    "description": "Prevent downloading execution logs as a CSV."
                  },
                  "hideCostInfo": {
                    "type": "boolean",
                    "description": "Withhold execution cost. Logs and member exports omit cost and token spend; organization-level data drains, configurable by org admins only, are not projected."
                  },
                  "disableKnowledgeBaseCreation": {
                    "type": "boolean",
                    "description": "Prevent creating knowledge bases, leaving existing ones queryable."
                  },
                  "disableKnowledgeBaseFileUpload": {
                    "type": "boolean",
                    "description": "Prevent uploading local documents, leaving sanctioned connectors as the only source."
                  },
                  "allowedKnowledgeConnectors": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Knowledge base connectors are limited to this list. Null permits every value; an empty list permits none."
                  },
                  "disableTableCreation": {
                    "type": "boolean",
                    "description": "Prevent creating tables, leaving existing ones usable."
                  },
                  "disableTableExport": {
                    "type": "boolean",
                    "description": "Prevent downloading a whole table as CSV or JSON."
                  },
                  "disableBulkFileDownload": {
                    "type": "boolean",
                    "description": "Prevent downloading folders as an archive."
                  },
                  "disablePersonalCredentials": {
                    "type": "boolean",
                    "description": "Prevent connecting personal credentials, leaving only workspace-shared ones."
                  },
                  "disableWorkspaceCreation": {
                    "type": "boolean",
                    "description": "Prevent creating new workspaces, which no existing group would govern. Read from the organization's default group, because creating a workspace names none."
                  },
                  "hideOrgMemberDirectory": {
                    "type": "boolean",
                    "description": "Withhold the member directory. Members cannot see the names or email addresses of other members. Read from the organization's default group, because the directory belongs to the organization and names no workspace."
                  },
                  "disableCliAccess": {
                    "type": "boolean",
                    "description": "Prevent approving a CLI login or using Sim CLI OAuth tokens for the public API. A login naming one of this group's workspaces is refused; an account-level login names none, so it is read from the organization's default group."
                  },
                  "disableWebhookTriggers": {
                    "type": "boolean",
                    "description": "Prevent making a workflow reachable from an inbound webhook."
                  },
                  "disableToolAutoApproval": {
                    "type": "boolean",
                    "description": "Prevent silencing a tool confirmation, so every call is confirmed again."
                  },
                  "hideSandboxesTab": {
                    "type": "boolean",
                    "description": "Revoke the Sandboxes module. Members cannot view, create, or change a workspace sandbox."
                  },
                  "disableOAuthAppAccess": {
                    "type": "boolean",
                    "description": "Prevent OAuth apps from accessing this group's workspaces. The organization's default group also governs authorizing apps and refreshing their access."
                  },
                  "disableKnowledgeBaseExport": {
                    "type": "boolean",
                    "description": "Prevent downloading a whole knowledge base as an archive."
                  },
                  "deniedPartialAccessProjectIssues": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 255
                    },
                    "description": "Issues in the listed Projects are unavailable to teammates without access to every active environment."
                  },
                  "defaultAgentModel": {
                    "default": null,
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Default model for new Agent blocks. Null uses the platform default."
                  },
                  "deniedAccessRequests": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 1024
                    },
                    "description": "Access requests are unavailable for the listed canonical target keys when access is restricted."
                  }
                },
                "required": [
                  "allowedIntegrations",
                  "allowedModelProviders",
                  "deniedModels",
                  "deniedTools",
                  "hideTraceSpans",
                  "hideKnowledgeBaseTab",
                  "hideTablesTab",
                  "hideCopilot",
                  "hideIntegrationsTab",
                  "hideSecretsTab",
                  "hideApiKeysTab",
                  "hideInboxTab",
                  "hideFilesTab",
                  "disableMcpTools",
                  "disableCustomTools",
                  "disableSkills",
                  "disableInvitations",
                  "disablePublicApi",
                  "disablePublicFileSharing",
                  "allowedFileShareAuthTypes",
                  "hideDeployApi",
                  "hideDeployMcp",
                  "hideDeployChatbot",
                  "allowedChatDeployAuthTypes",
                  "disablePersonalApiKeys",
                  "disableLogExport",
                  "hideCostInfo",
                  "disableKnowledgeBaseCreation",
                  "disableKnowledgeBaseFileUpload",
                  "allowedKnowledgeConnectors",
                  "disableTableCreation",
                  "disableTableExport",
                  "disableBulkFileDownload",
                  "disablePersonalCredentials",
                  "disableWorkspaceCreation",
                  "hideOrgMemberDirectory",
                  "disableCliAccess",
                  "disableWebhookTriggers",
                  "disableToolAutoApproval",
                  "hideSandboxesTab",
                  "disableOAuthAppAccess",
                  "disableKnowledgeBaseExport",
                  "deniedPartialAccessProjectIssues",
                  "defaultAgentModel",
                  "deniedAccessRequests"
                ],
                "additionalProperties": false,
                "description": "Resolved group settings. True disables a boolean capability; null allowlists permit every value and empty allowlists permit none. defaultAgentModel selects the default for new Agent blocks without restricting model selection."
              },
              "isDefault": {
                "type": "boolean",
                "description": "Whether this is the organization fallback group. It governs a human caller with no applicable workspace-specific group; its own membership assignments do not limit its audience. Organization-level actions use the default group."
              },
              "membershipMode": {
                "type": "string",
                "description": "When no explicit assignments exist, an `inherit` group governs every member in its targeted workspaces. An empty `explicit` group, including a SCIM-managed group, governs nobody."
              },
              "workspaceIds": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Workspaces governed by a non-default group. Empty for the default group."
              },
              "createdBy": {
                "type": "string",
                "description": "User who created the group."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the group was created."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the group was last updated."
              }
            },
            "required": [
              "id",
              "organizationId",
              "name",
              "description",
              "config",
              "isDefault",
              "membershipMode",
              "workspaceIds",
              "createdBy",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "title": "Permission group",
            "description": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Get permission group response",
        "description": "The group, its resolved settings, and workspace scope.",
        "examples": [
          {
            "data": {
              "id": "group-123",
              "organizationId": "org-123",
              "name": "Restricted",
              "description": null,
              "config": {
                "allowedIntegrations": null,
                "allowedModelProviders": null,
                "deniedModels": [],
                "deniedTools": [],
                "hideTraceSpans": false,
                "hideKnowledgeBaseTab": false,
                "hideTablesTab": false,
                "hideCopilot": false,
                "hideIntegrationsTab": false,
                "hideSecretsTab": false,
                "hideApiKeysTab": false,
                "hideInboxTab": false,
                "hideFilesTab": false,
                "disableMcpTools": false,
                "disableCustomTools": false,
                "disableSkills": false,
                "disableInvitations": false,
                "disablePublicApi": false,
                "disablePublicFileSharing": false,
                "allowedFileShareAuthTypes": null,
                "hideDeployApi": false,
                "hideDeployMcp": false,
                "hideDeployChatbot": false,
                "allowedChatDeployAuthTypes": null,
                "disablePersonalApiKeys": false,
                "disableLogExport": false,
                "hideCostInfo": false,
                "disableKnowledgeBaseCreation": false,
                "disableKnowledgeBaseFileUpload": false,
                "allowedKnowledgeConnectors": null,
                "disableTableCreation": false,
                "disableTableExport": false,
                "disableBulkFileDownload": false,
                "disablePersonalCredentials": false,
                "disableWorkspaceCreation": false,
                "hideOrgMemberDirectory": false,
                "disableCliAccess": false,
                "disableWebhookTriggers": false,
                "disableToolAutoApproval": false,
                "hideSandboxesTab": false,
                "disableOAuthAppAccess": false,
                "disableKnowledgeBaseExport": false,
                "deniedPartialAccessProjectIssues": [],
                "defaultAgentModel": null,
                "deniedAccessRequests": []
              },
              "isDefault": false,
              "membershipMode": "inherit",
              "workspaceIds": [
                "workspace-123"
              ],
              "createdBy": "admin-123",
              "createdAt": "2026-06-01T09:00:00.000Z",
              "updatedAt": "2026-06-01T09:00:00.000Z"
            }
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": {
              "id": "group-123",
              "organizationId": "org-123",
              "name": "Restricted",
              "description": null,
              "config": {
                "allowedIntegrations": null,
                "allowedModelProviders": null,
                "deniedModels": [],
                "deniedTools": [],
                "hideTraceSpans": false,
                "hideKnowledgeBaseTab": false,
                "hideTablesTab": false,
                "hideCopilot": false,
                "hideIntegrationsTab": false,
                "hideSecretsTab": false,
                "hideApiKeysTab": false,
                "hideInboxTab": false,
                "hideFilesTab": false,
                "disableMcpTools": false,
                "disableCustomTools": false,
                "disableSkills": false,
                "disableInvitations": false,
                "disablePublicApi": false,
                "disablePublicFileSharing": false,
                "allowedFileShareAuthTypes": null,
                "hideDeployApi": false,
                "hideDeployMcp": false,
                "hideDeployChatbot": false,
                "allowedChatDeployAuthTypes": null,
                "disablePersonalApiKeys": false,
                "disableLogExport": false,
                "hideCostInfo": false,
                "disableKnowledgeBaseCreation": false,
                "disableKnowledgeBaseFileUpload": false,
                "allowedKnowledgeConnectors": null,
                "disableTableCreation": false,
                "disableTableExport": false,
                "disableBulkFileDownload": false,
                "disablePersonalCredentials": false,
                "disableWorkspaceCreation": false,
                "hideOrgMemberDirectory": false,
                "disableCliAccess": false,
                "disableWebhookTriggers": false,
                "disableToolAutoApproval": false,
                "hideSandboxesTab": false,
                "disableOAuthAppAccess": false,
                "disableKnowledgeBaseExport": false,
                "deniedPartialAccessProjectIssues": [],
                "defaultAgentModel": null,
                "deniedAccessRequests": []
              },
              "isDefault": false,
              "membershipMode": "inherit",
              "workspaceIds": [
                "workspace-123"
              ],
              "createdBy": "admin-123",
              "createdAt": "2026-06-01T09:00:00.000Z",
              "updatedAt": "2026-06-01T09:00:00.000Z"
            }
          }
        }
      }
    }
  }
}

```

### 400

```json

{
  "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "BAD_REQUEST",
          "message": "Invalid request"
        }
      }
    }
  }
}

```

### 401

```json

{
  "description": "The API credential is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNAUTHORIZED",
          "message": "Authentication required"
        }
      }
    }
  }
}

```

### 403

```json

{
  "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "FORBIDDEN",
          "message": "Insufficient workspace permissions",
          "details": {
            "code": "INSUFFICIENT_WORKSPACE_ROLE"
          }
        }
      }
    }
  }
}

```

### 404

```json

{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found"
        }
      }
    }
  }
}

```

### 429

```json

{
  "description": "The caller exceeded the request rate limit.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "RATE_LIMITED",
          "message": "API rate limit exceeded",
          "details": {
            "retryAfter": "2026-01-01T00:00:30.000Z"
          }
        }
      }
    }
  }
}

```

### 500

```json

{
  "description": "An unexpected server error occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "Internal server error"
        }
      }
    }
  }
}

```

### 503

```json

{
  "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Service temporarily unavailable"
        }
      }
    }
  }
}

```

## Referenced schemas

The following definitions preserve recursive references and composition exactly.

```json

{
  "#/components/headers/X-RateLimit-Limit": {
    "description": "Maximum requests allowed in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit",
      "description": "Maximum requests allowed in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Remaining": {
    "description": "Requests remaining in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit remaining",
      "description": "Requests remaining in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Reset": {
    "description": "ISO 8601 timestamp when the current rate-limit window resets.",
    "schema": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "title": "Rate limit reset",
      "description": "ISO 8601 timestamp when the current rate-limit window resets."
    }
  },
  "#/components/schemas/GetPermissionGroupResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2PermissionGroup"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Get permission group response",
    "description": "The group, its resolved settings, and workspace scope.",
    "examples": [
      {
        "data": {
          "id": "group-123",
          "organizationId": "org-123",
          "name": "Restricted",
          "description": null,
          "config": {
            "allowedIntegrations": null,
            "allowedModelProviders": null,
            "deniedModels": [],
            "deniedTools": [],
            "hideTraceSpans": false,
            "hideKnowledgeBaseTab": false,
            "hideTablesTab": false,
            "hideCopilot": false,
            "hideIntegrationsTab": false,
            "hideSecretsTab": false,
            "hideApiKeysTab": false,
            "hideInboxTab": false,
            "hideFilesTab": false,
            "disableMcpTools": false,
            "disableCustomTools": false,
            "disableSkills": false,
            "disableInvitations": false,
            "disablePublicApi": false,
            "disablePublicFileSharing": false,
            "allowedFileShareAuthTypes": null,
            "hideDeployApi": false,
            "hideDeployMcp": false,
            "hideDeployChatbot": false,
            "allowedChatDeployAuthTypes": null,
            "disablePersonalApiKeys": false,
            "disableLogExport": false,
            "hideCostInfo": false,
            "disableKnowledgeBaseCreation": false,
            "disableKnowledgeBaseFileUpload": false,
            "allowedKnowledgeConnectors": null,
            "disableTableCreation": false,
            "disableTableExport": false,
            "disableBulkFileDownload": false,
            "disablePersonalCredentials": false,
            "disableWorkspaceCreation": false,
            "hideOrgMemberDirectory": false,
            "disableCliAccess": false,
            "disableWebhookTriggers": false,
            "disableToolAutoApproval": false,
            "hideSandboxesTab": false,
            "disableOAuthAppAccess": false,
            "disableKnowledgeBaseExport": false,
            "deniedPartialAccessProjectIssues": [],
            "defaultAgentModel": null,
            "deniedAccessRequests": []
          },
          "isDefault": false,
          "membershipMode": "inherit",
          "workspaceIds": [
            "workspace-123"
          ],
          "createdBy": "admin-123",
          "createdAt": "2026-06-01T09:00:00.000Z",
          "updatedAt": "2026-06-01T09:00:00.000Z"
        }
      }
    ]
  },
  "#/components/schemas/V2PermissionGroup": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Permission group identifier."
      },
      "organizationId": {
        "type": "string",
        "description": "Organization that owns the group."
      },
      "name": {
        "type": "string",
        "description": "Group name, unique within the organization."
      },
      "description": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Optional description of the group."
      },
      "config": {
        "type": "object",
        "properties": {
          "allowedIntegrations": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none."
          },
          "allowedModelProviders": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Model providers are limited to this list. Null permits every value; an empty list permits none."
          },
          "deniedModels": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Models listed in this list are blocked."
          },
          "deniedTools": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Integration tools listed in this list are blocked."
          },
          "hideTraceSpans": {
            "type": "boolean",
            "description": "Withhold per-block trace spans from logs and from the API."
          },
          "hideKnowledgeBaseTab": {
            "type": "boolean",
            "description": "Revoke the Knowledge Base module. Members cannot open, search, or query any knowledge base."
          },
          "hideTablesTab": {
            "type": "boolean",
            "description": "Revoke the Tables module. Members cannot read or write any table."
          },
          "hideCopilot": {
            "type": "boolean",
            "description": "Revoke Chat. Members cannot ask Sim to build or edit anything."
          },
          "hideIntegrationsTab": {
            "type": "boolean",
            "description": "Revoke integration connections. Members cannot view, add, or remove an OAuth connection."
          },
          "hideSecretsTab": {
            "type": "boolean",
            "description": "Revoke secrets. Members cannot read, add, or change a workspace environment variable."
          },
          "hideApiKeysTab": {
            "type": "boolean",
            "description": "Revoke workspace API keys. Members cannot list, create, or revoke one."
          },
          "hideInboxTab": {
            "type": "boolean",
            "description": "Revoke the Sim Mailer inbox. Members cannot read or send mail."
          },
          "hideFilesTab": {
            "type": "boolean",
            "description": "Revoke the Files module. Members cannot list, upload, or download workspace files."
          },
          "disableMcpTools": {
            "type": "boolean",
            "description": "Block agents from calling MCP tools."
          },
          "disableCustomTools": {
            "type": "boolean",
            "description": "Block agents from calling user-defined custom tools."
          },
          "disableSkills": {
            "type": "boolean",
            "description": "Block agents from loading skills."
          },
          "disableInvitations": {
            "type": "boolean",
            "description": "Prevent inviting anyone to a workspace or to the organization."
          },
          "disablePublicApi": {
            "type": "boolean",
            "description": "Revoke public API access. Calls to a deployed workflow are refused."
          },
          "disablePublicFileSharing": {
            "type": "boolean",
            "description": "Revoke public file sharing. Members cannot create a share link."
          },
          "allowedFileShareAuthTypes": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "public",
                    "password",
                    "email",
                    "sso"
                  ]
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Public file-share authentication is limited to this list. Null permits every value; an empty list permits none."
          },
          "hideDeployApi": {
            "type": "boolean",
            "description": "Prevent deploying a workflow as an API endpoint."
          },
          "hideDeployMcp": {
            "type": "boolean",
            "description": "Prevent exposing a workflow as an MCP server."
          },
          "hideDeployChatbot": {
            "type": "boolean",
            "description": "Prevent deploying a workflow as a chat."
          },
          "allowedChatDeployAuthTypes": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "public",
                    "password",
                    "email",
                    "sso"
                  ]
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Chat deployment authentication is limited to this list. Null permits every value; an empty list permits none."
          },
          "disablePersonalApiKeys": {
            "type": "boolean",
            "description": "Prevent members from using a personal API key against this workspace."
          },
          "disableLogExport": {
            "type": "boolean",
            "description": "Prevent downloading execution logs as a CSV."
          },
          "hideCostInfo": {
            "type": "boolean",
            "description": "Withhold execution cost. Logs and member exports omit cost and token spend; organization-level data drains, configurable by org admins only, are not projected."
          },
          "disableKnowledgeBaseCreation": {
            "type": "boolean",
            "description": "Prevent creating knowledge bases, leaving existing ones queryable."
          },
          "disableKnowledgeBaseFileUpload": {
            "type": "boolean",
            "description": "Prevent uploading local documents, leaving sanctioned connectors as the only source."
          },
          "allowedKnowledgeConnectors": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Knowledge base connectors are limited to this list. Null permits every value; an empty list permits none."
          },
          "disableTableCreation": {
            "type": "boolean",
            "description": "Prevent creating tables, leaving existing ones usable."
          },
          "disableTableExport": {
            "type": "boolean",
            "description": "Prevent downloading a whole table as CSV or JSON."
          },
          "disableBulkFileDownload": {
            "type": "boolean",
            "description": "Prevent downloading folders as an archive."
          },
          "disablePersonalCredentials": {
            "type": "boolean",
            "description": "Prevent connecting personal credentials, leaving only workspace-shared ones."
          },
          "disableWorkspaceCreation": {
            "type": "boolean",
            "description": "Prevent creating new workspaces, which no existing group would govern. Read from the organization's default group, because creating a workspace names none."
          },
          "hideOrgMemberDirectory": {
            "type": "boolean",
            "description": "Withhold the member directory. Members cannot see the names or email addresses of other members. Read from the organization's default group, because the directory belongs to the organization and names no workspace."
          },
          "disableCliAccess": {
            "type": "boolean",
            "description": "Prevent approving a CLI login or using Sim CLI OAuth tokens for the public API. A login naming one of this group's workspaces is refused; an account-level login names none, so it is read from the organization's default group."
          },
          "disableWebhookTriggers": {
            "type": "boolean",
            "description": "Prevent making a workflow reachable from an inbound webhook."
          },
          "disableToolAutoApproval": {
            "type": "boolean",
            "description": "Prevent silencing a tool confirmation, so every call is confirmed again."
          },
          "hideSandboxesTab": {
            "type": "boolean",
            "description": "Revoke the Sandboxes module. Members cannot view, create, or change a workspace sandbox."
          },
          "disableOAuthAppAccess": {
            "type": "boolean",
            "description": "Prevent OAuth apps from accessing this group's workspaces. The organization's default group also governs authorizing apps and refreshing their access."
          },
          "disableKnowledgeBaseExport": {
            "type": "boolean",
            "description": "Prevent downloading a whole knowledge base as an archive."
          },
          "deniedPartialAccessProjectIssues": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "description": "Issues in the listed Projects are unavailable to teammates without access to every active environment."
          },
          "defaultAgentModel": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Default model for new Agent blocks. Null uses the platform default."
          },
          "deniedAccessRequests": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1024
            },
            "description": "Access requests are unavailable for the listed canonical target keys when access is restricted."
          }
        },
        "required": [
          "allowedIntegrations",
          "allowedModelProviders",
          "deniedModels",
          "deniedTools",
          "hideTraceSpans",
          "hideKnowledgeBaseTab",
          "hideTablesTab",
          "hideCopilot",
          "hideIntegrationsTab",
          "hideSecretsTab",
          "hideApiKeysTab",
          "hideInboxTab",
          "hideFilesTab",
          "disableMcpTools",
          "disableCustomTools",
          "disableSkills",
          "disableInvitations",
          "disablePublicApi",
          "disablePublicFileSharing",
          "allowedFileShareAuthTypes",
          "hideDeployApi",
          "hideDeployMcp",
          "hideDeployChatbot",
          "allowedChatDeployAuthTypes",
          "disablePersonalApiKeys",
          "disableLogExport",
          "hideCostInfo",
          "disableKnowledgeBaseCreation",
          "disableKnowledgeBaseFileUpload",
          "allowedKnowledgeConnectors",
          "disableTableCreation",
          "disableTableExport",
          "disableBulkFileDownload",
          "disablePersonalCredentials",
          "disableWorkspaceCreation",
          "hideOrgMemberDirectory",
          "disableCliAccess",
          "disableWebhookTriggers",
          "disableToolAutoApproval",
          "hideSandboxesTab",
          "disableOAuthAppAccess",
          "disableKnowledgeBaseExport",
          "deniedPartialAccessProjectIssues",
          "defaultAgentModel",
          "deniedAccessRequests"
        ],
        "additionalProperties": false,
        "description": "Resolved group settings. True disables a boolean capability; null allowlists permit every value and empty allowlists permit none. defaultAgentModel selects the default for new Agent blocks without restricting model selection."
      },
      "isDefault": {
        "type": "boolean",
        "description": "Whether this is the organization fallback group. It governs a human caller with no applicable workspace-specific group; its own membership assignments do not limit its audience. Organization-level actions use the default group."
      },
      "membershipMode": {
        "type": "string",
        "description": "When no explicit assignments exist, an `inherit` group governs every member in its targeted workspaces. An empty `explicit` group, including a SCIM-managed group, governs nobody."
      },
      "workspaceIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Workspaces governed by a non-default group. Empty for the default group."
      },
      "createdBy": {
        "type": "string",
        "description": "User who created the group."
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "description": "When the group was created."
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "description": "When the group was last updated."
      }
    },
    "required": [
      "id",
      "organizationId",
      "name",
      "description",
      "config",
      "isDefault",
      "membershipMode",
      "workspaceIds",
      "createdBy",
      "createdAt",
      "updatedAt"
    ],
    "additionalProperties": false,
    "title": "Permission group",
    "description": "Response data."
  },
  "#/components/responses/BadRequest": {
    "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "BAD_REQUEST",
            "message": "Invalid request"
          }
        }
      }
    }
  },
  "#/components/schemas/V2Error": {
    "type": "object",
    "properties": {
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the error."
          },
          "details": {
            "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/V2ActionableForbiddenDetails"
              },
              {
                "description": "Other structured context defined by the specific error."
              }
            ]
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false,
        "description": "Canonical error details."
      }
    },
    "required": [
      "error"
    ],
    "additionalProperties": false,
    "title": "v2 error response",
    "description": "Canonical error envelope returned by the public v2 API.",
    "examples": [
      {
        "error": {
          "code": "BAD_REQUEST",
          "message": "The request is invalid."
        }
      }
    ]
  },
  "#/components/schemas/V2ActionableForbiddenDetails": {
    "type": "object",
    "properties": {
      "code": {
        "$ref": "#/components/schemas/V2ForbiddenDetailCode"
      }
    },
    "required": [
      "code"
    ],
    "additionalProperties": {
      "description": "Additional context for this refusal."
    },
    "title": "Actionable forbidden details",
    "description": "Machine-readable cause and optional context for an actionable `403` response."
  },
  "#/components/schemas/V2ForbiddenDetailCode": {
    "type": "string",
    "enum": [
      "INSUFFICIENT_WORKSPACE_ROLE",
      "PERSONAL_API_KEYS_DISABLED",
      "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
      "PRINCIPAL_KIND_NOT_PERMITTED",
      "ORGANIZATION_MEMBERSHIP_REQUIRED",
      "ORGANIZATION_ADMIN_REQUIRED",
      "ENTERPRISE_PLAN_REQUIRED",
      "SSO_DISABLED",
      "SSO_DOMAIN_NOT_VERIFIED",
      "SSO_PROVIDER_LIMIT_REACHED",
      "ORGANIZATION_PLAN_REQUIRED",
      "AUDIT_LOGS_DISABLED",
      "ACCESS_REQUESTS_DISABLED",
      "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
      "SKILL_EDITOR_ACCESS_REQUIRED",
      "SECRET_ADMIN_ACCESS_REQUIRED",
      "WORKSPACE_RESOURCE_LIMIT_REACHED",
      "PUBLIC_SHARING_NOT_ALLOWED",
      "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
      "MCP_SERVER_URL_NOT_ALLOWED",
      "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
      "CHAT_AUTH_MODE_NOT_PERMITTED",
      "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
      "PERMISSION_GROUP_CAPABILITY_BLOCKED",
      "INTEGRATION_NOT_ALLOWED",
      "INSUFFICIENT_SCOPE",
      "SCIM_MANAGED_MEMBERSHIP"
    ],
    "title": "Forbidden detail code",
    "description": "Stable cause code for an actionable `403` response."
  },
  "#/components/responses/Unauthorized": {
    "description": "The API credential is missing or invalid.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNAUTHORIZED",
            "message": "Authentication required"
          }
        }
      }
    }
  },
  "#/components/responses/Forbidden": {
    "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "FORBIDDEN",
            "message": "Insufficient workspace permissions",
            "details": {
              "code": "INSUFFICIENT_WORKSPACE_ROLE"
            }
          }
        }
      }
    }
  },
  "#/components/responses/NotFound": {
    "description": "The requested resource was not found.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "NOT_FOUND",
            "message": "Not found"
          }
        }
      }
    }
  },
  "#/components/responses/RateLimited": {
    "description": "The caller exceeded the request rate limit.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "RATE_LIMITED",
            "message": "API rate limit exceeded",
            "details": {
              "retryAfter": "2026-01-01T00:00:30.000Z"
            }
          }
        }
      }
    }
  },
  "#/components/headers/Retry-After": {
    "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Retry after",
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
    }
  },
  "#/components/responses/InternalError": {
    "description": "An unexpected server error occurred.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "INTERNAL_ERROR",
            "message": "Internal server error"
          }
        }
      }
    }
  },
  "#/components/responses/ServiceUnavailable": {
    "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "SERVICE_UNAVAILABLE",
            "message": "Service temporarily unavailable"
          }
        }
      }
    }
  }
}

```

[Download OpenAPI specification](/openapi.json)

Source: `openapi-v2-resources.json`, operation `getPermissionGroup`.