> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.ekanos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities and permissions

> Marketing copy for the integration detail page read by users and security reviewers.

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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
// ✅ 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](/sdk/surfaces/proposes) — declare tool classifications for workflows
* [Integration shape](/sdk/integration-shape) — full definition structure


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.