> ## 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.

# Access

> Declare what each screen reads and changes, and what each tool reaches, so admins see it and agent access can be suggested from screens.

`access` is an optional declaration that says what your integration touches. On a widget it says what the screen **reads** and which **actions** it offers. On a tool it says which **resource** the tool reads or writes and how far it reaches.

Ekanos uses it in two places:

* **Admins see it.** When an admin places your widget on a workspace, they see what that screen reads and changes, in your words.
* **Agent access is suggested from screens.** When an admin lets a group's assistant use your integration, Ekanos suggests the reads and actions of the screens that group can see. Screens only suggest. An admin accepts each suggestion, and nothing is granted for them.

## Declare it on a widget

```ts theme={null}
components: {
  widgets: [
    {
      id: 'acme-payments-receivables',
      name: 'Receivables',
      component: ReceivablesWidget,
      widgetState: 'active',
      access: {
        reads: [
          { resource: 'invoices', label: 'Open invoices' },
          { resource: 'ar_aging', label: 'AR aging' },
        ],
        actions: [
          {
            id: 'mark-paid',
            label: 'Mark paid',
            permission: 'invoices.update', // optional
            operations: ['record_payment', 'update_invoice'],
            reach: 'record',
          },
        ],
      },
    },
  ],
}
```

* **`reads`** — one entry per kind of data the screen shows. `resource` is a lowercase id (`invoices`, `action_items`); `label` is what an admin reads, up to 80 characters.
* **`actions`** — one entry per thing a person can change from the screen. `id` is kebab-case and unique on the screen. `label` is the button's name.
* **`operations`** — the tools that action runs, by tool name. At least one.
* **`reach`** — how far the action goes: `'record'` (one record), `'many'` (several records) or `'outside'` (it sends something out of the system, such as an email).
* **`permission`** — optional, `resource.action`. Leave it out and the host applies its own default.

Both `reads` and `actions` are optional, so a read-only widget declares only `reads`.

## Declare it on a tool

```ts theme={null}
tools: [
  {
    name: 'record_payment',
    description: 'Record a payment against one invoice.',
    parameters: { /* … */ },
    access: {
      resource: 'payments',
      verb: 'write',
      reach: { records: 'one' },
    },
    async run(ctx, args) {
      // …
    },
  },
  {
    name: 'send_invoice_reminder',
    description: 'Email a payment reminder for one invoice.',
    parameters: { /* … */ },
    access: {
      resource: 'invoices',
      verb: 'write',
      reach: { records: 'one', sendsOutside: true },
    },
    async run(ctx, args) {
      // …
    },
  },
],
```

* **`resource`** — the same ids your screens use in `reads`, so a screen's read and the tool behind it line up.
* **`verb`** — `'read'` or `'write'`.
* **`reach.records`** — `'one'` or `'many'`: how many records one call can touch.
* **`reach.sendsOutside`** — `true` when a call sends something out of the system. Leave it out otherwise.

`reach` is optional. A tool with no `reach` is shown to admins as "reach unknown", and Ekanos never claims it matches a screen.

## Optional, and what happens without it

You can ship without `access`. An undeclared screen behaves at **product level**: it renders for any group that has your product, and it suggests nothing for agents. An admin who wants an assistant to use your integration then grants the whole product, rather than accepting suggestions per screen. An undeclared tool is reachable only through that product-level grant.

Declare it when you want admins to see, and grant, only what a screen needs.

## Broader than the screen

An action's `reach` says what the screen does. The tools behind it can do more. Ekanos compares them and flags a tool as **broader than the screen** when:

* the tool reaches `many` records and the action reaches `record`, or
* the tool sends outside the system (`sendsOutside: true`) and the action's reach is not `'outside'`.

A broader tool is still listed, but it is offered unticked, so an admin has to choose it on purpose. A tool with no declared `reach` is listed as "reach unknown" for the same reason.

For example, a **Mark paid** action with `reach: 'record'` that runs `update_invoice`, a tool that can rewrite any field on any invoice, will be flagged. That is honest, not a defect. If you want the suggestion ticked, give the action a narrower tool, such as one that only records a payment.

## Best practices

* **Declare every screen and tool that touches data**, not a sample. A half-declared integration suggests half of what it does.
* **Match what the screen really does.** Declare `reach: 'outside'` for anything that sends an email, message or webhook. Understating it makes an admin's decision worse.
* **Share resource ids.** Use one id per kind of data across widgets and tools: `invoices`, not `invoice` in one place and `open_invoices` in another.
* **Write labels for a business owner.** `Open invoices` and `Mark paid`, not endpoint names.
* **Split broad tools.** Prefer a narrow tool for each screen action over one tool that edits everything.
* **Name real operations.** Every entry in `operations` should be a tool you ship. Use the tool's declared name.
* **Declare `reach` on every tool.** It is optional, but it is what lets a screen's suggestion be ticked by default.

## Next steps

* [Widgets](https://sdk.ekanos.dev/sdk/surfaces/widgets.md) for the declaration `access` sits on
* [Tools](https://sdk.ekanos.dev/sdk/surfaces/tools.md) for the tool declaration
* [Managed agents](https://sdk.ekanos.dev/guides/managed-agents.md) for how agents use the access an admin accepts


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