SIGNALS Docs

Plugin Connections

Declare encrypted credentials, OAuth authorization and connection-scoped network access.

Overview

SDK 2.1 connections let operators configure integration credentials without plugin views or routes. Declare sdk: "^2.1" and a vendor-prefixed key. Installation connections are shared by a package; user connections belong to the signed-in user. multiple: true is only valid for installation scope.

connections:
  - key: acme.ledger
    label: Ledger
    scope: installation
    multiple: false
    permission: acme.ledger.manage
    auth: oauth2
    fields:
      - { name: client_id, label: Client ID, required: true }
      - { name: client_secret, label: Client secret, type: password, secret: true, required: true }
      - { name: server, label: Service URL, type: url, extends_network: true }
    oauth:
      grant: authorization_code
      authorization_url: https://api.example.com/authorize
      token_url: https://api.example.com/token
      revoke_url: https://api.example.com/revoke
      client_id_field: client_id
      client_secret_field: client_secret
      client_auth: basic
      scopes: [contacts.read]
      organisations:
        url: https://api.example.com/organisations
        list_path: ""
        id_path: id
        label_path: name
        selection: required
    test: true
permissions: [acme.ledger.manage]
network: [api.example.com]

Authentication kinds are none, api_key, basic and oauth2. The first three save encrypted configuration; the plugin adds any headers itself. OAuth grants are authorization_code and client_credentials. Client credentials forbids authorization, identity and organisation endpoints. client_auth selects post or basic credentials on the token exchange.

Fields use the channel configuration rules: string/text, textarea, integer, boolean, email, HTTPS URL, password and select. Select needs options. Names must be unique; OAuth credential references must name fields. Mark secrets explicitly. Saved secret fields are represented by the unchanged-value mask, never their plaintext, in the core form.

Authorization and organisations

Operator saves configuration → POST Connect → authority authorization page
→ callback checks one-use session state, actor, permission and PKCE
→ encrypted token exchange → guarded organisation lookup
→ one result selects automatically; several results require operator selection
→ connected

State expires after ten minutes. The callback never displays authority error text. An empty organisation list enters an error state. At most 200 offered organisations are retained, encrypted, until selection; the server validates the selected ID against those offers. IDs are capped at 191 characters and labels at 255.

Connections appear in the Plugin Manager Connections tab and user connections in personal notification settings under Connected apps. A plugin page can also declare:

sections:
  - {type: connections, key: connection, connection: acme.ledger}

Installation management requires the declared permission or plugins.manage. Personal management requires ownership and the declared permission. Every mutation and OAuth callback checks again.

SDK handles and testing

$connection = $context->connection('acme.ledger');
$response = $connection->request()->get('https://api.example.com/contacts');

$registrar->connectionTester('acme.ledger', function ($context, $connection) {
    $response = $connection->request()->get('https://api.example.com/health');
    return $response->successful()
        ? \App\Sdk\Connections\ConnectionTestResult::ok('Service available')
        : \App\Sdk\Connections\ConnectionTestResult::failed('Service unavailable');
});

connection($key, $id = null) resolves a live row; multiple matches require an explicit ID. connections($key) lists installation connections or the current user's own personal connections. Plugins cannot create or configure connections through the SDK. Undeclared tester keys fail registration and signals:plugin check --wire.

The public App\Sdk\Connections\PluginConnection handle exposes readonly id, key, status, userId, organisationId, organisationLabel, and connectedAt. Its methods are config($field = null, $default = null), accessToken(), http(), request(), recordFailure($reason), and isConnected(). config() includes decrypted secrets only under the package boundary; never copy it to logs or rendered data. OAuth request() adds a bearer token. Other authentication kinds return a plain guarded request.

App\Sdk\Connections\PluginConnectionException::$reason is one of not_declared, not_connected, reconnect_required, revoked, ambiguous, forbidden, or refresh_retryable. App\Sdk\Connections\ConnectionTestResult has readonly ok and message properties and ok($message) / failed($message) factories.

In the framework test harness, $this->fakeConnection('acme.ledger', config: [], tokens: ['access_token' => 'test', 'expires_in' => 3600]) creates a connected encrypted row without real OAuth. Optional organisationId and user arguments select its organisation and personal owner. Pair this with Http::fake() and the normal HTTP guard fixtures.

Network, rotation and lifecycle

Network access is the manifest's exact host list plus the selected connection's saved HTTPS extends_network URLs. {server}/token can use such a URL field; ordinary placeholders are URL encoded. Endpoints reject userinfo and fragments. No wildcards, suffix matches or redirects are allowed. DNS/IP validation and connection pinning run on every send. A connection's grants never apply to another connection, package or ordinary context HTTP client.

Refresh occurs within 60 seconds of expiry under a tenant-scoped atomic lock. Missing rotated refresh tokens retain the existing token. Only an OAuth invalid_grant refresh response enters error with reconnect_required and short-circuits later attempts until reconnect. Lock contention, network failures, provider errors and invalid_client preserve tokens and connection status and raise refresh_retryable; retry with backoff. Changing the client ID or a network URL clears tokens. Changes to descriptor scopes, endpoints or network fields require reconnect; a disabled package cannot use its connections. Uninstall attempts remote revoke, then clears local secrets and retains a revoked audit record even if the authority is unavailable.

Configuration, tokens and offered organisations are encrypted and hidden from serialization and audits. Audit records include package, connection identity and changed field names, with refresh audit events throttled to once an hour. Test messages and recorded failures are sanitized and limited to 500 characters.

For payments.record_external, the connection key is the integration mapping provider and the selected organisation is the default external tenant. Revoked or disconnected connections cannot record or replay payments. See External payments.

Only an OAuth invalid_grant response marks a refresh as requiring reconnect. Lock contention, network failures, provider errors and invalid_client leave the connection status and tokens intact and raise refresh_retryable; background jobs should retry with backoff. Fresh cached tokens bypass the refresh lock.