Cloud account setup

The current feature supports account setup, verification, and connection management. An active connection does not yet supply credentials to executing flows. Runtime credential issuance and a dagy.connections Python interface are not available. For a working data integration today, configure the credentials supported by your workflow node or Python client, using secrets.

Before you start

Open Integrations → Cloud accounts in the correct workspace. If the feature is unavailable, its API returns 404; your workspace administrator can confirm availability.

For API examples, set $DAGY_API_URL to your workspace API URL and $DAGY_TOKEN to an authenticated token; see authentication. Reading requires connections.read, editing requires connections.write, verification requires connections.verify, and deletion requires connections.delete.

Use the setup artifacts generated for your connection. They contain identity values specific to your workspace; substituting values from another connection can break verification or weaken access boundaries.

Create a connection

Choose a provider, a display name, a reference name (slug), and the resources to verify. The slug must contain 2–63 lowercase letters, digits, or hyphens and start with a letter or digit. Display names can contain up to 100 characters.

Choose read or readwrite. This determines generated permissions and verification checks. Declare the narrowest resources needed for your intended integration.

curl --fail-with-body "$DAGY_API_URL/cloud-connections" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Order archive",
    "slug": "order-archive",
    "provider": "aws",
    "auth_mode": "aws_assume_role",
    "identity": {"account_id": "123456789012", "home_region": "us-east-1"},
    "scope": {"resources": ["s3://example-orders/raw/*"], "access": "read"}
  }'

The 201 response contains connection and setup objects. Save connection.connection_id for later requests. Setup artifacts can contain callback credentials; share them only with the administrator performing setup.

Set up AWS access

AWS uses aws_assume_role: an IAM role in your account with a connection-specific External ID. This setup does not request long-lived AWS access keys.

1. Create the connection with its account ID, default region, and S3 resources.
2. Open Setup, review the generated CloudFormation or manual instructions, and create the role and permissions using those exact values.
3. For customer-managed KMS encryption, add key ARNs to scope.kms_key_arns. The key policy must also permit the role to use the key. Reapply generated permissions after changes.
4. Let the guided stack register the role, or register its ARN manually.
5. Run verification and resolve failed checks.

curl --fail-with-body "$DAGY_API_URL/cloud-connections/$CONNECTION_ID/aws/register" \
  -H "Authorization: Bearer $DAGY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"role_arn":"arn:aws:iam::123456789012:role/example-dagy-access"}'

Registration starts verification when available. The role must belong to the declared account. Only commercial arn:aws: roles are supported; GovCloud and China partitions are not supported by this connection flow.

Verification checks the account, role trust, attribution permissions, and declared resources. It also tests that missing and incorrect External IDs are rejected.

AWS External ID

ExternalIdNotEnforced means the role can be assumed without the correct External ID. Apply the generated trust policy and verify again. Do not bypass this failed check.

To rotate the External ID, use connection settings or POST /cloud-connections/{id}/external-id/rotate. Regenerate setup, update the role's trust policy, and verify again. Coordinate the Dagy change and cloud policy update.

Set up Azure access

The identity object includes tenant_id, optional subscription_ids, and client_id for customer-application modes. Resources identify Blob Storage containers/prefixes or Key Vaults.

1. Create the connection with your tenant and resource details.
2. Complete the consent or customer-application setup shown in the wizard.
3. Grant generated roles at the resource scope using the supplied Azure CLI commands or Bicep artifact.
4. Run verification. Review resource checks after identity verification succeeds.

For legacy mode, send secret: {"client_secret":"...","secret_expires_at":"YYYY-MM-DD"} at creation. Expiry must be in the future and within the accepted two-year range. Stored secrets are not returned. The cloud connection update request has no general secret-replacement field; plan a replacement connection when rotating a legacy credential.

Azure consent

Consent authorizes the application identity; it does not grant storage or vault data access. Complete resource role assignments separately.

For an invalid, expired, or already used consent link, request GET /cloud-connections/{id}/setup?rotate=true and use the new link. Role propagation can delay verification; retry after applying grants. For KeyVaultAccessPolicyModel, use a vault with Azure RBAC authorization and apply generated roles.

Set up Google Cloud access

Choose gcp_wif_aws for direct federated access or gcp_wif_aws_impersonate to impersonate a service account. This setup does not request service-account keys.

The identity object includes project_id, project_number, pool_id, and provider_id. New connections default to dagy-pool and dagy-aws. Impersonation requires service_account_email; billing_project is optional for BigQuery setup.

1. Create the connection with project identity and gs:// or bq:// resources.
2. Run generated gcloud commands to create the pool and provider.
3. Apply generated IAM grants to resources and, if applicable, the service account.
4. Use uniform bucket-level access for Cloud Storage. Review generated organization-policy and network guidance if your organization restricts federation or resource access.
5. Confirm changed pool/provider details with POST /cloud-connections/{id}/gcp/register, then verify.

Example registration body:

{"pool_id":"dagy-pool","provider_id":"dagy-aws","project_number":"123456789012"}

GCP attribute condition

Verification deliberately tries a different identity. AttributeConditionNotEnforced means that identity was accepted. Apply the exact generated attribute condition and verify again. A permissive condition cannot pass setup verification.

Verify and inspect status

curl --fail-with-body -X POST \
  "$DAGY_API_URL/cloud-connections/$CONNECTION_ID/verify" \
  -H "Authorization: Bearer $DAGY_TOKEN"

curl --fail-with-body \
  "$DAGY_API_URL/cloud-connections/$CONNECTION_ID/verification" \
  -H "Authorization: Bearer $DAGY_TOKEN"

202 means verification was accepted, not that access passed. Poll until the report is no longer queued or running. Inspect verification.checks, verification.summary, and verification.blocking_error alongside connection status.

Edit, bind, and revoke

PATCH /cloud-connections/{id} accepts name, description, scope, bindings, and pre-activation identity changes. Changing scope on an active connection marks it degraded until permissions are updated and verified. Identity is editable only in pending_setup or pending_admin_approval.

Use PUT /cloud-connections/{id}/bindings to save intended environment restrictions:

{
  "environments": {
    "production": {
      "enabled": true,
      "locations": ["dagy-aws"],
      "deployments": ["orders-production"],
      "max_ttl_seconds": 3600
    }
  },
  "require_declaration": true
}

Bindings are saved configuration. They do not currently enforce access in executing flows because runtime credential issuance is not implemented.

Use POST /cloud-connections/{id}/disable or /enable to change the record's enabled state. To revoke provider access, also remove or disable trust/grants in your cloud account. DELETE /cloud-connections/{id} returns 204 and removes the registration; it does not delete your cloud resources.

Trust errors

Cloud-specific failures have an object inside detail containing error_class, message, retryable, and remediation guidance. Use that guidance and the verification report rather than matching human-readable strings.

Limits: 50 connections per workspace, 25 resources per connection, 10 AWS KMS keys per connection, and accepted TTL settings of 900–3,600 seconds. These settings do not guarantee runtime credential availability.

See the API reference for all connection operations.