Capabilities and permissions

Capabilities and permissions are pure data: copy for the integration detail page, and they render on the activation dialog too, so the person connecting the integration reads every string. Write detail as a sentence you would be happy for a customer’s security reviewer to read.

Capabilities

What the integration does for the user:

capabilities: [
  {
    label: 'Volume at a glance',
    description: 'Gross volume, trend, and success/failure counts on one card.',
    icon: VolumeIcon, // Optional component reference — not rendered on the activation surface
  },
  {
    label: 'Refund tracking',
    description: 'See which payments were refunded and why.',
  },
],

Renders as:

What it does section
label, then — + description
icon is accepted by the schema but not rendered here

label and description are both required non-empty strings.

Permissions

What the integration can access:

permissions: [
  {
    label: 'Read payments',
    detail: 'Lists payments and aggregate volume for the connected merchant.',
    type: 'read',
  },
  {
    label: 'Issue refunds',
    detail: 'Submits refunds against payments for the connected merchant.',
    type: 'write',
  },
],

Renders as:

What it can access section
label, a badge reading Read or Write from type
detail on the line below

label, detail, and type are all required.

Writing for security review

Be honest and specific. A security reviewer will read this against your handlers’ actual behavior. Write the detail as a sentence a customer’s security team would want to read:

// ✅ Good — specific about what you access
{
  label: 'Read customer email addresses',
  detail: 'Fetches customer email addresses from the connected merchant account.',
  type: 'read',
}

// ❌ Bad — vague, hides what you do
{
  label: 'Customer data',
  detail: 'Access to customer information.',
  type: 'read',
}

// ❌ Misleading — doesn't match what the integration actually does
{
  label: 'Read merchants',
  detail: 'Lists merchant accounts.',
  type: 'read',
}

What doesn’t enforce access

Capabilities and permissions are disclosure only, not enforcement. What actually constrains you:

Storage schemas — only declared keys are readable/writable
Egress allowlist — only declared origins are reachable
Secret tiers — only account-tier secrets are writable

Declare capabilities and permissions truthfully so the reviewer can verify them against your code during promotion.

Declaration rules

Both arrays are optional — omit for a minimal integration
type is 'read' | 'write'
Each section is omitted entirely when its array is empty
type drives only the badge — it does not reorder or group anything
Both objects are strict: an unrecognized key is a validation error

Next steps

Proposes — declare tool classifications for workflows
Integration shape — full definition structure

Getting started

Fundamentals

Declarable surfaces

Development

Capabilities and permissions

Capabilities

Permissions

Writing for security review

What doesn’t enforce access

Declaration rules

Next steps

​Capabilities

​Permissions

​Writing for security review

​What doesn’t enforce access

​Declaration rules

​Next steps

Capabilities

Permissions

Writing for security review

What doesn’t enforce access

Declaration rules

Next steps