Preview organization access request

GET/api/v2/organizations/{organizationId}/access-requests/{requestId}/preview

Preview the current permission changes, affected group and audience, or member credit cap. Review canApply, changes, impact, and fingerprint before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization Admin access. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows

json

{
  "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"
    }
  }
}

OAuth scope: api:read.

Path parameters

organizationIdstringRequired

Organization that owns the access requests.

minLength: 1

requestIdstringRequired

Access request identifier.

minLength: 1
maxLength: 128

Responses

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

The proposed group or credit-cap change, affected audience, and fingerprint.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

The proposed group or credit-cap change, affected audience, and fingerprint.

1 field

datavalueRequired

Response data.

Schema details

Exactly one of

Option 1object

10 fields

newLimitCreditsvalueRequired

Applied credit cap for a fulfilled request; null before approval or for permission changes.

Schema details

Any of

Option 1number

minimum: 0

Option 2null

requestobjectRequired

Access request being reviewed.

12 fields

idstringRequired

Access request identifier.

minLength: 1
maxLength: 128

organizationIdstringRequired

Organization that owns the request.

minLength: 1

workspaceIdvalueRequired

Workspace where access was requested; null for an organization-level request.

Schema details

Any of

Option 1string

Unique workspace identifier.

minLength: 1
maxLength: 128

Option 2null

targetvalueRequired

The requested feature, integration, model, tool, authentication mode, or member credit cap.

Schema details

Exactly one of

Option 1object

2 fields

kindstringRequired

Kind of access being requested.

const: feature

configKeystringRequired

Feature restriction key returned by access discovery.

enum: ["hideTraceSpans","hideKnowledgeBaseTab","hideTablesTab","hideCopilot","hideIntegrationsTab","hideSecretsTab","hideApiKeysTab","hideInboxTab","hideFilesTab","disableMcpTools","disableCustomTools","disableSkills","disableInvitations","disablePublicApi","disablePublicFileSharing","hideDeployApi","hideDeployMcp","hideDeployChatbot","disablePersonalApiKeys","disableLogExport","hideCostInfo","disableKnowledgeBaseCreation","disableKnowledgeBaseFileUpload","disableTableCreation","disableTableExport","disableBulkFileDownload","disablePersonalCredentials","disableWorkspaceCreation","hideOrgMemberDirectory","disableCliAccess","disableWebhookTriggers","disableToolAutoApproval","hideSandboxesTab","disableOAuthAppAccess","disableKnowledgeBaseExport"]

Additional properties are not allowed.

Option 2object

2 fields

kindstringRequired

Kind of access being requested.

const: integration

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 3object

2 fields

kindstringRequired

Kind of access being requested.

const: provider

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 4object

2 fields

kindstringRequired

Kind of access being requested.

const: model

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 5object

2 fields

kindstringRequired

Kind of access being requested.

const: tool

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 6object

2 fields

kindstringRequired

Kind of access being requested.

const: knowledge_connector

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 7object

2 fields

kindstringRequired

Kind of access being requested.

const: file_share_auth

idstringRequired

Authentication mode to request.

enum: ["public","password","email","sso"]

Additional properties are not allowed.

Option 8object

2 fields

kindstringRequired

Kind of access being requested.

const: chat_deploy_auth

idstringRequired

Authentication mode to request.

enum: ["public","password","email","sso"]

Additional properties are not allowed.

Option 9object

2 fields

kindstringRequired

Kind of access being requested.

const: usage_limit

idstringRequired

Request an increase to the acting user’s member credit cap.

const: member

Additional properties are not allowed.

targetLabelstringRequired

Human-readable name of the requested access.

minLength: 1
maxLength: 512

reasonstringRequired

Reason supplied by the requester.

maxLength: 1000

statusstringRequired

Current request status.

enum: ["pending","fulfilled","declined","cancelled","closed"]

decisionReasonvalueRequired

Explanation for a declined or closed request; null when none was recorded.

Schema details

Any of

Option 1string

maxLength: 1000

Option 2null

createdAtstringRequired

When the request was submitted.

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))$

decidedAtvalueRequired

When the request was resolved; null while pending.

Schema details

Any of

Option 1string

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))$

Option 2null

groupNamevalueRequired

Name of the governing group when the request was submitted; null for credit-cap requests.

Schema details

Any of

Option 1string

Option 2null

requesterobjectRequired

User who submitted the request.

3 fields

idstringRequired

Requester user identifier.

minLength: 1
maxLength: 128

namevalueRequired

Requester display name.

Schema details

Any of

Option 1string

Option 2null

emailstringRequired

Requester email address.

maxLength: 320

Additional properties are not allowed.

changesarrayRequired

Permission changes proposed for the whole governing group.

maxItems: 43

Schema details

Array itemobject

4 fields

configKeystringRequired

Permission restriction changed by approval.

enum: ["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"]

labelstringRequired

Human-readable permission name.

minLength: 1
maxLength: 512

beforevalueRequired

Current value of the restriction.

Schema details

Any of

Option 1boolean

Option 2value

Integrations and blocks are limited to this list. Null permits every value; an empty list permits none.

Schema details

Any of

Option 1array

Schema details

Array itemstring

Option 2null

aftervalueRequired

Value after applying the request.

Schema details

Any of

Option 1boolean

Option 2value

Integrations and blocks are limited to this list. Null permits every value; an empty list permits none.

Schema details

Any of

Option 1array

Schema details

Array itemstring

Option 2null

Additional properties are not allowed.

impactobjectRequired

Members and workspaces affected by approval.

4 fields

memberCountintegerRequired

Number of affected members.

minimum: 0
maximum: 9007199254740991

workspaceCountintegerRequired

Number of affected workspaces.

minimum: 0
maximum: 9007199254740991

workspaceNamesarrayRequired

Names of affected workspaces, capped at 100.

maxItems: 100

Schema details

Array itemstring

truncatedbooleanRequired

Whether the workspace-name list is truncated; counts include the full impact.

Additional properties are not allowed.

fingerprintstringRequired

Pass to Resolve Organization Access Request after reviewing the changes and impact.

minLength: 1
maxLength: 128

canApplybooleanRequired

Whether this request can currently be approved.

unavailableReasonvalueRequired

Why approval is unavailable; null when canApply is true.

Schema details

Any of

Option 1string

maxLength: 1000

Option 2null

resolutionKindstringRequired

Approval changes the governing permission group.

const: permission

groupvalueRequired

Group affected by a permission approval; null for credit-cap changes.

Schema details

Any of

Option 1object

2 fields

idstringRequired

Governing group identifier.

minLength: 1
maxLength: 128

namestringRequired

Governing group name.

Additional properties are not allowed.

Option 2null

currentLimitCreditsnullRequired

Not applicable to permission changes.

Additional properties are not allowed.

Option 2object

10 fields

newLimitCreditsvalueRequired

Applied credit cap for a fulfilled request; null before approval or for permission changes.

Schema details

Any of

Option 1number

minimum: 0

Option 2null

requestobjectRequired

Access request being reviewed.

12 fields

idstringRequired

Access request identifier.

minLength: 1
maxLength: 128

organizationIdstringRequired

Organization that owns the request.

minLength: 1

workspaceIdvalueRequired

Workspace where access was requested; null for an organization-level request.

Schema details

Any of

Option 1string

Unique workspace identifier.

minLength: 1
maxLength: 128

Option 2null

targetvalueRequired

The requested feature, integration, model, tool, authentication mode, or member credit cap.

Schema details

Exactly one of

Option 1object

2 fields

kindstringRequired

Kind of access being requested.

const: feature

configKeystringRequired

Feature restriction key returned by access discovery.

enum: ["hideTraceSpans","hideKnowledgeBaseTab","hideTablesTab","hideCopilot","hideIntegrationsTab","hideSecretsTab","hideApiKeysTab","hideInboxTab","hideFilesTab","disableMcpTools","disableCustomTools","disableSkills","disableInvitations","disablePublicApi","disablePublicFileSharing","hideDeployApi","hideDeployMcp","hideDeployChatbot","disablePersonalApiKeys","disableLogExport","hideCostInfo","disableKnowledgeBaseCreation","disableKnowledgeBaseFileUpload","disableTableCreation","disableTableExport","disableBulkFileDownload","disablePersonalCredentials","disableWorkspaceCreation","hideOrgMemberDirectory","disableCliAccess","disableWebhookTriggers","disableToolAutoApproval","hideSandboxesTab","disableOAuthAppAccess","disableKnowledgeBaseExport"]

Additional properties are not allowed.

Option 2object

2 fields

kindstringRequired

Kind of access being requested.

const: integration

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 3object

2 fields

kindstringRequired

Kind of access being requested.

const: provider

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 4object

2 fields

kindstringRequired

Kind of access being requested.

const: model

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 5object

2 fields

kindstringRequired

Kind of access being requested.

const: tool

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 6object

2 fields

kindstringRequired

Kind of access being requested.

const: knowledge_connector

idstringRequired

Identifier returned by access discovery.

minLength: 1
maxLength: 512

Additional properties are not allowed.

Option 7object

2 fields

kindstringRequired

Kind of access being requested.

const: file_share_auth

idstringRequired

Authentication mode to request.

enum: ["public","password","email","sso"]

Additional properties are not allowed.

Option 8object

2 fields

kindstringRequired

Kind of access being requested.

const: chat_deploy_auth

idstringRequired

Authentication mode to request.

enum: ["public","password","email","sso"]

Additional properties are not allowed.

Option 9object

2 fields

kindstringRequired

Kind of access being requested.

const: usage_limit

idstringRequired

Request an increase to the acting user’s member credit cap.

const: member

Additional properties are not allowed.

targetLabelstringRequired

Human-readable name of the requested access.

minLength: 1
maxLength: 512

reasonstringRequired

Reason supplied by the requester.

maxLength: 1000

statusstringRequired

Current request status.

enum: ["pending","fulfilled","declined","cancelled","closed"]

decisionReasonvalueRequired

Explanation for a declined or closed request; null when none was recorded.

Schema details

Any of

Option 1string

maxLength: 1000

Option 2null

createdAtstringRequired

When the request was submitted.

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))$

decidedAtvalueRequired

When the request was resolved; null while pending.

Schema details

Any of

Option 1string

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))$

Option 2null

groupNamevalueRequired

Name of the governing group when the request was submitted; null for credit-cap requests.

Schema details

Any of

Option 1string

Option 2null

requesterobjectRequired

User who submitted the request.

3 fields

idstringRequired

Requester user identifier.

minLength: 1
maxLength: 128

namevalueRequired

Requester display name.

Schema details

Any of

Option 1string

Option 2null

emailstringRequired

Requester email address.

maxLength: 320

Additional properties are not allowed.

changesarrayRequired

Permission changes proposed for the whole governing group.

maxItems: 43

Schema details

Array itemobject

4 fields

configKeystringRequired

Permission restriction changed by approval.

enum: ["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"]

labelstringRequired

Human-readable permission name.

minLength: 1
maxLength: 512

beforevalueRequired

Current value of the restriction.

Schema details

Any of

Option 1boolean

Option 2value

Integrations and blocks are limited to this list. Null permits every value; an empty list permits none.

Schema details

Any of

Option 1array

Schema details

Array itemstring

Option 2null

aftervalueRequired

Value after applying the request.

Schema details

Any of

Option 1boolean

Option 2value

Integrations and blocks are limited to this list. Null permits every value; an empty list permits none.

Schema details

Any of

Option 1array

Schema details

Array itemstring

Option 2null

Additional properties are not allowed.

impactobjectRequired

Members and workspaces affected by approval.

4 fields

memberCountintegerRequired

Number of affected members.

minimum: 0
maximum: 9007199254740991

workspaceCountintegerRequired

Number of affected workspaces.

minimum: 0
maximum: 9007199254740991

workspaceNamesarrayRequired

Names of affected workspaces, capped at 100.

maxItems: 100

Schema details

Array itemstring

truncatedbooleanRequired

Whether the workspace-name list is truncated; counts include the full impact.

Additional properties are not allowed.

fingerprintstringRequired

Pass to Resolve Organization Access Request after reviewing the changes and impact.

minLength: 1
maxLength: 128

canApplybooleanRequired

Whether this request can currently be approved.

unavailableReasonvalueRequired

Why approval is unavailable; null when canApply is true.

Schema details

Any of

Option 1string

maxLength: 1000

Option 2null

resolutionKindstringRequired

Approval raises the requester’s member credit cap.

const: usage_limit

groupnullRequired

Credit-cap requests do not change a permission group.

currentLimitCreditsvalueRequired

Current member credit cap. Approval requires a higher newLimitCredits.

Schema details

Any of

Option 1number

minimum: 0
maximum: 9007199254740991

Option 2null

Additional properties are not allowed.

Response example 1

json

{
  "data": {
    "resolutionKind": "permission",
    "request": {
      "id": "request-123",
      "organizationId": "org-123",
      "workspaceId": "workspace-123",
      "target": {
        "kind": "feature",
        "configKey": "hideTablesTab"
      },
      "targetLabel": "Tables",
      "reason": "Maintain team data",
      "status": "pending",
      "decisionReason": null,
      "createdAt": "2026-06-01T09:00:00.000Z",
      "decidedAt": null,
      "groupName": "Engineering",
      "requester": {
        "id": "user-123",
        "name": "Alex Example",
        "email": "alex@example.com"
      }
    },
    "group": {
      "id": "group-123",
      "name": "Engineering"
    },
    "changes": [
      {
        "configKey": "hideTablesTab",
        "label": "Tables",
        "before": true,
        "after": false
      }
    ],
    "impact": {
      "memberCount": 2,
      "workspaceCount": 1,
      "workspaceNames": [
        "Engineering"
      ],
      "truncated": false
    },
    "fingerprint": "current-preview-fingerprint",
    "canApply": true,
    "unavailableReason": null,
    "currentLimitCredits": null,
    "newLimitCredits": null
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum: 0
maximum: 9007199254740991

X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum: 0
maximum: 9007199254740991

X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

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))$

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

The API credential is missing or invalid.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

The requested resource was not found.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

The request conflicts with current resource state.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "CONFLICT",
    "message": "The request conflicts with the current state of the resource"
  }
}

The caller exceeded the request rate limit.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

An unexpected server error occurred.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

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.

@layer base { .docs-root [data-docs-tab-panel][hidden] { display: block !important; } } .docs-root [data-docs-tabs-root] [role="tablist"], .docs-root [data-docs-tabs-select] { display: none; }

object

Canonical error envelope returned by the public v2 API.

1 field

errorobjectRequired

Canonical error details.

3 fields

codestringRequired

Stable machine-readable error code.

messagestringRequired

Human-readable explanation of the error.

detailsvalue

Structured error context whose keys depend on the error. Actionable 403 responses use the V2ActionableForbiddenDetails shape; validation failures may return issue arrays instead.

Schema details

Any of

Option 1object

Machine-readable cause and optional context for an actionable 403 response.

1 field

codestringRequired

Stable cause code for an actionable 403 response.

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"]

Additional propertiesvalue

Additional context for this refusal.

Option 2value

Other structured context defined by the specific error.

Additional properties are not allowed.

Example

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Response headers

Retry-Afterinteger

Seconds to wait before retrying, sent on 429 and 503. Add jitter rather than retrying at exactly this offset.

minimum: 0
maximum: 9007199254740991

Authentication

Path parameters

Responses

200

Response example 1

Response headers

400

401

403

404

409

429

Response headers

500

503

Response headers