> ## Documentation Index > Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt > Use this file to discover all available pages before exploring further. # Automation connections > Select and govern the organization-scoped KayanOS connection required by every released automation before configuring triggers or actions. ## A KayanOS connection is required first Every released KayanOS Automations trigger and action requires a selected **KayanOS connection**. It is an organization-scoped authorization boundary for the automation, not merely a box for external credentials. Select it before choosing a trigger, mapping fields, or testing an action. An internal outcome—such as creating a KayanOS record, starting a task, rendering a document, returning a dashboard response, or sending an internal KayanOS notification—may not need an external account. It still needs the KayanOS connection selected for the flow. Add an external authorization only when the approved service outcome genuinely crosses into an external system. The practical question is therefore two-part: 1. Which approved KayanOS connection authorizes this automation within the organization? 2. Does this specific outcome also need an external system/account, and if so what is the smallest approved additional authorization? Do not solve a connection error by selecting a broader or personal connection. Correct the organization-owned connection, its owner, access boundary, or authorization state instead. ## Connection ownership model Every connection needs an accountable organizational owner. It must never depend on one employee's personal account or an undocumented credential. | Record before authorization | Why it matters | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Business purpose | States the specific service outcome, such as retrieving an approved reference value or sending a permitted internal update. | | Organization owner | Owns renewal, review, revocation, and operational decisions. | | Technical owner | Can diagnose configuration and availability issues. | | Data classification | Identifies which data may leave or enter KayanOS and which fields are prohibited. | | Allowed actions | Limits the connection to the smallest necessary read, write, or notification scope. | | Authentication and rotation owner | Knows how credentials are stored, rotated, and revoked without interrupting the service unexpectedly. | | Failure behavior | States whether the automation stops, creates an internal review task, retries through an approved process, or follows another documented path. | ## Approve a connection before building with it 1. **Define the outcome.** Describe what the automation must achieve. State whether it stays inside KayanOS or also requires an approved external system. 2. **Map data fields.** List the exact values that cross the boundary. Exclude citizen data, staff data, attachments, or internal notes unless their transfer is explicitly approved. 3. **Choose least privilege.** Request only the required organization, project, service, table, or endpoint scope. Prefer read access over write access where possible. 4. **Assign owners.** Record business, technical, and credential-rotation owners before authorization. 5. **Plan revocation.** Know how the connection will be disabled and how the automation behaves afterward. 6. **Use a non-production path.** Validate it with approved non-production records and recipients before touching a production service scope. 7. **Document the review.** Keep the purpose, scope, test evidence, and expiry/review date with the automation's operating record. ## Configure safely in KayanOS When creating or selecting a connection in the automation editor: * Select the organization-owned connection that matches the approved purpose; do not create a duplicate personal variant. * Confirm its label, owner, current validity, and permitted scope before mapping fields. Reconnect/re-authorize it through the approved owner path when the editor reports it is no longer valid. * Map only the values approved for that connection. Avoid passing a whole record when the target needs one identifier or status. * Keep write actions behind the same explicit conditions you would use for a built-in KayanOS action. * Ensure a failed connection creates an internal, reviewable outcome rather than silently dropping the service request. ## Test plan for a connection-backed flow | Test | What to verify | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | KayanOS connection selection | The flow uses the intended organization-owned connection and the editor accepts its authorization state. | | Authorized positive case | The connection reaches only the approved service and produces the expected minimum result. | | Missing/invalid input | The automation stops safely or follows the approved review path; it does not send malformed or partial data. | | Permission boundary | A request outside the approved scope is denied or excluded. | | Duplicate/retry | A retry does not create repeated external or internal outcomes. | | Connection failure | A missing, expired, revoked, incorrectly scoped, or externally unauthorized connection is visible to the operational owner and the automation behaves as documented. | | Revocation | Disabling the connection prevents further use and leaves existing KayanOS records reviewable. | ## Diagnose a connection before changing the flow | Symptom | Check first | Safe response | | --------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | No connection can be selected | Organization context, released catalog access, and automation builder permission. | Switch to the correct organization or ask the automation owner to provide the approved connection; do not use a personal substitute. | | Connection is rejected during test | Connection validity/authorization, owner, selected purpose, and target scope. | Reconnect or renew through the recorded owner path, then repeat one non-production test. | | Trigger test works but action fails | Selected connection, action target, runtime role/scope, and mapped values. | Preserve the run ID and test data; correct one boundary before retrying a side-effecting action. | | Connection was revoked or owner changed | Revocation/change record and flow dependency inventory. | Stop dependent flows, assign/review a replacement organization-owned connection, and test before re-enabling. | | Unexpected data crossed a boundary | Field mapping, action output, connection purpose, and recipient/target. | Stop the flow if needed, preserve safe evidence, and follow the organization’s data-incident process. | ## Guardrails * Never paste secrets, access tokens, private keys, or connection credentials into an expression, record field, task note, document template, or screenshot. * Do not use a connection to bypass KayanOS permissions or a required human approval. * Do not enable broad external writes during initial testing. * Re-review the connection when its owner, scope, endpoint, data classification, or service purpose changes. Internal record, form, task, document, dashboard-response, and notification outcomes may not require an external account, but every released KayanOS Automation still starts with its selected KayanOS connection. ![KayanOS Automations connection selector for an approved organization-owned connection.](https://kayanos.app/docs-images/en/build/automations-connections.png) ## Continue building * Select an event in [KayanOS Automations triggers](/build/automations-triggers). * Map the outcome in [KayanOS Automations actions](/build/automations-actions). * Review [permissions and availability](/reference/permissions-and-availability) before authorizing or widening any connection scope.