SIGNALS Docs

Plugin integration identities

Consent, permission scopes and revocable background execution for plugins.

Overview

SDK 2.1 lets a plugin run background work as a consented integration identity. Use this when scheduled jobs need the same guarded data and action permissions as an acting user. The identity belongs to the installation, persists for audit history, and cannot sign in or receive API tokens.

Declare and grant

sdk: "^2.1"
data_access:
  - entity: accounts
    fields: [id, name, email]
    operations: [read, list]
integration_principal:
  label: Ledger identity
  reason: Synchronise contact names in the background.
  permissions: [accounts.view, accounts.identity.view]
  fields:
    accounts: [id, name]
  warehouses: grant

The administrator first accepts the capability consent, then opens the plugin details and selects Grant integration identity, including all or selected warehouses. The panel shows permissions, fields, status, generation, last use and granting administrator. The administrator must hold plugins.manage, every requested permission and the warehouse scope being granted. Owners may grant otherwise permitted permissions, but cannot bypass the denylist.

Denied permissions are owner, plugins.*, users.*, roles.*, api.*, settings.manage, security.*, accounts.privacy.* impersonate*, webhooks.manage, workflows.*, notifications.manage, email-templates.manage, accounts.merge and accounts.delete. Permissions must exist in the core registry or be declared by the plugin.

CLI grants and revocations require an explicit active administrator:

php artisan signals:plugin principal acme/ledger-sync --grant --acting-user=12 --warehouses=1,2
php artisan signals:plugin principal acme/ledger-sync --show --json
php artisan signals:plugin principal acme/ledger-sync --revoke --acting-user=12

Use --warehouses=all for unrestricted access when the administrator can grant that scope. A grant is the organisation's decision: deactivating the granting administrator does not revoke it. Regranting increments the generation and reuses the historical identity row.

Execute background work

if ($context->hasIntegrationPrincipal()) {
    $context->asIntegrationPrincipal(function () use ($context): void {
        $contacts = $context->list('accounts');
    });
}

asIntegrationPrincipal returns the callback result. It restores authentication, actor context and package scope even after an exception. It refuses execution in every HTTP route, including public and verified inbound routes, and inside a signed-in person's session. Dispatch a PluginJob onto an asynchronous queue instead; QUEUE_CONNECTION=sync executes inside the originating request and cannot run an integration identity. The public PluginPrincipalException exposes a reason, including not_granted, suspended, revoked and interactive_session.

For a job extending App\Sdk\Jobs\PluginJob, opt in with protected bool $runsAsIntegrationPrincipal = true;. For a declared schedule, set principal: true; this applies to both callable handlers and job classes. Neither option serializes the dispatching user's authentication.

Permission, field and warehouse boundaries

The identity has direct permissions and no roles, owner flag or account membership. The normal action gates and warehouse checks still run. fields intersects the manifest's readable fields; an entity omitted from this map retains its normal manifest field clamp. Account field groups also require their normal permission, so granting the email field alone does not grant accounts.contact-pii.view.

Each principal read and list emits plugin.data_read with actor: integration, principal ID and generation; operations and updates carry the same attribution. Grant, suspend and revoke events are audited. Creator displays use Integration: <label> even though normal user queries exclude integration identities.

Disabling a plugin suspends its grant. Re-enabling resumes it only when consent is unchanged. Capability changes suspend it until an administrator regrants. Manual revocation and uninstall remove permissions immediately and retain the identity row for historical foreign keys. Each runner entry and SDK data entry checks the current grant; stale generations cannot continue using data access.

Test in the sandbox app

Inside App\Sdk\Testing\PluginTestCase, call $this->actingAsIntegrationPrincipal(warehouseIds: [1]) to create a real grant, then execute through $this->context()->asIntegrationPrincipal(...). The optional permissions argument narrows the declared permissions for denial tests. Authentication is cleared before runtime entry. See Plugin testing for the sandbox app workflow.

For background external payment recording, grant payments.record and invoices.view plus the required warehouses, declare payments.record_external, and call it inside asIntegrationPrincipal. The payment creator is the identity user and the operation audit includes its principal ID and generation.

Warehouse limits cover invoices, rentals, assets, accounts, payments, credit notes, purchase orders, vehicles, warehouses and activities through their related subject. Unassigned accounts and vehicles remain visible. Identity updates also require entity read permission and the granted warehouse. A read or list resolves the grant once for consistent projection; the next SDK call rechecks revocation. Purchase-order costs use core cost visibility; roleless identities can receive them through a direct costs.view grant.

SDK 2.2 allows granted identities to record external refunds and reversals (payments.record, invoices.view), allocate their own invoice credit notes (credit-notes.apply, invoices.view), and set PO billing markers (purchase_orders.view, purchase_orders.edit, costs.view). Warehouse and account privacy limits apply on first execution. Receipt replay checks current actor permissions and connection access, then returns the stored result before current record visibility lookups.