---
id: UJ-029
title: Connect an integration, API key, webhook, or automation
actors: [OWNER, ADMIN]
surface: app.zync.is/settings/integrations and app.zync.is/settings/api-keys
goal: Extend Zync safely while keeping credentials, scopes, delivery, and usage visible.
trigger: Admin connects a provider or creates an API/webhook credential.
preconditions:
  - Integration/module enabled; admin has settings/credential permission.
success_state: Connection/key/webhook is active with scope, status, usage, and revocation controls.
source_specs:
  - docs/specs/2026-05-31-integration-hub.md
  - docs/specs/2026-05-31-api-keys-ui.md
  - docs/specs/2026-05-31-public-api-docs.md
  - docs/specs/2026-05-31-webhook-endpoint-detail.md
  - docs/specs/2026-06-01-zapier-make-integration.md
  - docs/specs/2026-06-01-oauth-authorization-code.md
  - docs/specs/2026-05-31-api-usage-quota-ui.md
  - docs/specs/2026-05-31-tenant-public-api.md
---

## Happy path

1. Admin selects provider/integration → completes OAuth or enters configuration in the provider-owned flow.
2. Zync validates callback/credentials, encrypts secrets, and shows connection health/scopes.
3. Admin creates API key or webhook endpoint → chooses least-privilege scopes, copies secret once, and stores it securely.
4. External client sends request/event → Zync authenticates, rate-limits, processes idempotently, and records usage/delivery attempt.
5. Admin inspects usage/delivery history, rotates/revokes key, retries failed webhook, or disconnects provider.

## Alternate and failure paths

- OAuth denied/expired, invalid signature, quota exceeded, revoked key, or provider outage → reject safely and expose actionable status without secret disclosure.
- Webhook delivery fails → retry according to policy and surface terminal failure.

## Permissions and boundaries

- Credentials are tenant-scoped; API scopes cannot exceed the admin's allowed capabilities.
- Public API and webhook authentication are separate from staff session authentication.

## Source specs

- `docs/specs/2026-05-31-integration-hub.md`
- `docs/specs/2026-05-31-api-keys-ui.md`
- `docs/specs/2026-05-31-public-api-docs.md`
- `docs/specs/2026-05-31-webhook-endpoint-detail.md`
- `docs/specs/2026-06-01-zapier-make-integration.md`
- `docs/specs/2026-06-01-oauth-authorization-code.md`
- `docs/specs/2026-05-31-api-usage-quota-ui.md`
- `docs/specs/2026-05-31-tenant-public-api.md`