Quickstart: Connect an AWS Account
Create an AWS integration through the API and run its first extraction, end to end.
This quickstart connects an AWS account to Catio through the API and runs its first extraction. By the end you will have an integration on a daily schedule and a run you can watch to completion.
You need: an API key with integrationTypes.read, integrations.create, integrations.trigger, and integrationRuns.read (see Authentication), and permission to create an IAM role in the AWS account. The examples use curl and assume your key is in CATIO_API_KEY.
1. Look up what the integration type needs
curl https://api.catio.tech/v1/integration-types/aws \
-H "Authorization: Bearer $CATIO_API_KEY"The response lists the type's properties (name, whether it is required or secret, and any allowed values), identifiedBy (the properties that make an integration unique, for aws the account id), and setup: the IAM role Catio assumes in your account, with its roleName, the managed policyArns to attach, and the trustedPrincipalArn to trust.
2. Create the IAM role
- Generate a random external id of at least 16 characters, for example with
openssl rand -hex 16. - In the AWS account, create the role named in
setup.roleName, trustingsetup.trustedPrincipalArnwith your external id as thests:ExternalIdcondition. - Attach the policies in
setup.policyArns.
The external id is what stops anyone who learns your account id from assuming the role. For what the role allows and why, see AWS Integration.
3. Create the integration
curl -X POST https://api.catio.tech/v1/integrations \
-H "Authorization: Bearer $CATIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "aws",
"name": "prod-123456789012",
"properties": {
"AWS_ACCOUNT_ID": "123456789012",
"AWS_EXTERNAL_ID": "<your external id>",
"AWS_REGIONS_LIST": "*"
},
"schedule": { "enabled": true, "intervalHours": 24 }
}'A new integration returns 201 with the integration, including its id and nextRunAt. Creating it starts its schedule. AWS_REGIONS_LIST takes * for all regions or a comma-separated list; a narrower list runs faster but leaves everything outside it invisible to Catio.
Running the same request again is safe: if the integration already exists with the same properties, the API returns it with 200. If it exists with different properties, you get 409 with the code integration_exists and the existing integration's id in existingId. Update it with PATCH instead.
4. Start a run
The schedule will run the integration on its own. To run it now:
curl -X POST https://api.catio.tech/v1/integrations/<integration id>/runs \
-H "Authorization: Bearer $CATIO_API_KEY"The call returns at once with 202 and a runId; it does not wait for the run. If a run is already active, it returns 200 with that run and created: false.
5. Watch the run
curl https://api.catio.tech/v1/integrations/<integration id>/runs/<run id> \
-H "Authorization: Bearer $CATIO_API_KEY"status is running, succeeded, failed, or cancelled. stages shows progress through the run, and messages holds its errors and warnings, oldest first. Poll at a modest interval until the status is no longer running.
Done when
- The integration appears in the console under Integrations, with a schedule and a next run.
- The run's status is
succeeded, and the account's resources appear in Stacks for any workspace subscribed to the integration.
If the run fails, its messages say why. A failure to assume the role usually means the trust policy, the external id, or the role name does not match. See Integration Troubleshooting.
Next
- Rotate the external id or change the schedule with
PATCH /v1/integrations/{id}, sending only what changes. - Errors and Rate Limits and Versioning before you put this in a pipeline.
Updated 9 days ago
