Connectivity API Quick Start

What You’ll Learn

Understand core concepts: connectors, resources, actions, credentials, executions
List available connectors and render them in your app
Inspect resources/actions to auto-generate config UIs
Create and store user credentials
Execute actions
Handle errors, logging, and production readiness

Key Concepts

Term	Definition
Connector	A packaged integration for a third-party app (e.g., Klaviyo, Shippo). Each connector exposes resources and actions.
Resource	A connector-defined entity (e.g., Order, Address) that bundles its schema and associated actions.
Action	An operation available on a resource (e.g., CreateAddress). Defines method, path, params, and responses.
Credential	The user’s authentication with a third-party app (OAuth 2.0, API key, etc.) required to run actions.
Execution	A single run of an action. Returns third-party response plus Alloy metadata.

Prerequisites

API Key: Generate in Alloy Dashboard → Settings → API Keys
Required headers:
- Authorization: Bearer <YOUR_API_KEY>
- x-api-version: 2025-09
Store API keys securely (e.g., Secrets Manager, Vault). Never expose them client-side.

Step 0: Create a User

Create a user record in Alloy Automation Platform before managing credentials or executions for each of your end-users. We support multi-tenancy so you can securely isolate each user’s data and credentials.

curl --request POST \
  --url https://production.runalloy.com/users \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09' \
  --data '{
    "fullName": "Jane Merchant",
    "username": "merchant_123@example.com"
  }'

Response:

{
    "userId": "689593e23e4c93cae95fd75c"
}

Save the userId and pass it as userId in subsequent calls.

Step 1: Discover Connectors

List all available connectors to power your app’s integration marketplace. You can use this data to render logos, names of the integration you support on your app.

curl --request GET \
  --url https://production.runalloy.com/connectors \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'

Example response:

{
   "connectors": [
      {
        "id": "hubspot",
        "name": "Hubspot",
        "icon": "https://cdn.runalloy.com/icons/hubspot.png",
        "group": [
            "input"
        ],
        "category": [
            "crm",
            "oas"
        ]
      },
      ...
   ]
}

Use this data to render logos, names, etc. You’ll need the id in later steps as connectorId.

Step 2: Explore Resources & Actions

List resources

You can list resources for a connector to discover the available entities and their actions. For example, if you application is integrating with Hubspot, you can dynamically create a list of actions a end-user can perform for Hubspot.

curl --request GET \
  --url https://production.runalloy.com/connectors/{connectorId}/resources \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'

Example response:

{
    "resources": [
       {
            "name": "contacts",
            "description": "Manage contacts.",
            "actions": [
                {
                    "id": "gdprDeleteContacts",
                    "name": "GDPR delete contacts",
                    "description": "Perform a GDPR delete operation on a list of contacts."
                },
                {
                    "id": "listContacts",
                    "name": "List contacts",
                    "description": "Retrieve a list of contacts, with pagination."
                },
                ...
            ]
        },
        ...
    ]
}

Get action details

You can get action details to fetch the action schema and parameters. For example, if you application is integrating with Hubspot, you can get the action details for the createContact action.

curl --request GET \
  --url https://production.runalloy.com/connectors/{connectorId}/actions/{actionId} \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'

Example response:

{
    "action": {
        "id": "createContact",
        "displayName": "Create a contact",
        "description": "Create a new contact record.",
        "httpMethod": "post",
        "path": "/crm/v3/objects/contacts",
        "parameters": [],
        "requestBody": {
            "type": "object",
            "required": [
                "properties"
            ],
            "properties": {
                "properties": {
                    "type": "object",
                    "required": [
                        "firstname",
                        "lastname",
                        "email"
                    ],
                    "properties": {
                        "firstname": {
                            "type": "string"
                        },
                        "lastname": {
                            "type": "string"
                        },
                        "email": {
                            "type": "string"
                        },
                        "company": {
                            "type": "string"
                        },
                        "website": {
                            "type": "string"
                        },
                        "phone": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "sampleSuccessResponse": {
            "id": "string",
            "properties": {
                "firstname": "string",
                "lastname": "string",
                "email": "string",
                "createdate": "2025-08-01T15:32:45.646Z",
                "lastmodifieddate": "2025-08-01T15:32:45.646Z"
            },
            "createdAt": "2025-08-01T15:32:45.646Z",
            "updatedAt": "2025-08-01T15:32:45.646Z",
            "archived": true
        }
    }
}

Step 3: Manage Credentials

Before executing actions, you need to create a credential for a user for a specific connector.

Check credential requirements

Before creating a credential, you need to check the credential requirements for the connector.

curl --request GET \
  --url https://production.runalloy.com/connectors/{connectorId}/credentials/metadata \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'

Example response:

{
    "metadata": [
        {
            "authenticationType": "oauth2",
            "properties": [
                {
                    "name": "userId",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "redirectUri",
                    "required": true,
                    "type": "string"
                }
            ]
        }
    ]
}

Create credential

You can create a credential for a user for a specific connector.

curl --request POST \
  --url https://production.runalloy.com/connectors/{connectorId}/credentials \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "abc123",
    "authenticationType": "oauth2",
    "redirectUri": "https://yourapp.com/oauth/callback"
  }'

Example response: For OAuth, redirect user to returned oauthUrl where user will authorize your app. For API key/HTTP auth, you’ll get credentialId immediately.

List credentials for a User

curl --request GET \
  --url https://production.runalloy.com/connectors/{connectorId}/credentials \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'

Example response:

{
    "credentials": [
        {
            "credentialId": "6895sdba313a2ebsdfd9bbd97",
            "name": "Jane Merchant's Hubspot",
            "type": "hubspot-oauth2",
            "createdAt": "2025-08-08T06:36:53.748Z",
            "updatedAt": "2025-08-08T06:36:53.748Z"
        }
    ]
}

Save the credentialId and pass it as credentialId in subsequent calls.

Step 4: Execute an Action

This is where you perform the actual action for a specific connectors. For example to create a contact in Hubspot, you would use hubspot as connectorId and createContact as actionId. credentialId is the credentialId you got from the previous step. queryParameters, requestBody, additionalHeaders, and pathParams are the parameters you got from the action details step.

curl --request POST \
  --url https://production.runalloy.com/connectors/{connectorId}/actions/{actionId}/execute \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09' \
  --header 'Content-Type: application/json' \
  --data '{
    "credentialId": "6895sdba313a2ebsdfd9bbd97",
    "queryParameters": {},
    "requestBody": {},
    "additionalHeaders": {},
    "pathParams": {}
  }'

Returns raw third-party payload in responseData.

Error Handling & Observability

All endpoints return structured error responses:

{
  "error": {
    "source": "THIRD_PARTY" | "CONNECTIVITY_API",
    "code": "INVALID_INPUT" | "INTERNAL_ERROR" | ...,
    "message": "...",
    "details": { "httpStatusCode": 404 }
  }
}

Best Practices:

Show human-friendly messages; log technical details
Retry on 429/5xx
Add monitoring/logging for executions

Next Steps

Browse the full API reference
Talk to your Alloy partner manager about upcoming connectors
Send feedback or open a support ticket

Happy building!

Getting Started

Documentation Index

​What You’ll Learn

​Key Concepts

​Prerequisites

​Step 0: Create a User

​Step 1: Discover Connectors

​Step 2: Explore Resources & Actions

​List resources

​Get action details

​Step 3: Manage Credentials

​Check credential requirements

​Create credential

​List credentials for a User

​Step 4: Execute an Action

​Error Handling & Observability

​Next Steps

What You’ll Learn

Key Concepts

Prerequisites

Step 0: Create a User

Step 1: Discover Connectors

Step 2: Explore Resources & Actions

List resources

Get action details

Step 3: Manage Credentials

Check credential requirements

Create credential

List credentials for a User

Step 4: Execute an Action

Error Handling & Observability

Next Steps