Authentication

Create an API key in Settings, send it as a bearer token, and grant only the permissions each key needs.

Every request to the Catio API is authenticated with an API key sent as a bearer token. A key belongs to one organization and holds a set of permissions; each operation names the permission it needs.

Create an API key

Admins create keys in the Catio console.

  1. Go to Settings > API keys.
  2. Click New API key, name it after the script or pipeline that will use it, and choose its permissions.
  3. Copy the key and store it in your secret manager or CI secret store.

The API keys page lists each key's permissions, status, creator, expiry, and when it was last used. Keys start with catio_.

Send the key

Put the key in the Authorization header of every request:

Authorization: Bearer catio_...

Your first call, listing the integration types the API can create:

curl https://api.catio.tech/v1/integration-types \
  -H "Authorization: Bearer $CATIO_API_KEY"

A missing or invalid key returns the unauthenticated error. A valid key without the permission an operation needs returns forbidden, and the error's permission field names the one it lacks. See Errors.

Permissions

Give each key only the permissions its job needs. A pipeline that only triggers runs does not need integrations.delete.

PermissionOperations
integrationTypes.readList integration types, get an integration type
integrations.readList integrations, get an integration
integrations.createCreate an integration
integrations.updateUpdate an integration
integrations.deleteDelete an integration
integrations.triggerStart a run
integrationRuns.readList runs, get a run

Keep keys safe

  • Store keys in a secret manager, never in source code or client-side code.
  • Use one key per script or pipeline, so a key can be revoked without breaking anything else.
  • Integrations created with a key record it as their creator (apikey:<key id>), so you can trace what a key has done.

Next

Quickstart: Connect an AWS Account


Did this page help you?