Access

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.

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

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 for the declaration access sits on
Tools for the tool declaration
Managed agents for how agents use the access an admin accepts

Getting started

Fundamentals

Declarable surfaces

Development

Declare it on a widget

Declare it on a tool

Optional, and what happens without it

Broader than the screen

Best practices

Next steps