> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectivity API Quick Start

> In this guide, we’ll explore how to use Alloy Automation’s Connectivity API to implement third party connectors in under 10 minutes. The Connectivity API makes it easy to build realtime, native, integration experiences into your product with a single REST Interface. Access thousands of APIs instantly.

## 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.

```bash theme={null}
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:

```json theme={null}
{
    "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.

```bash theme={null}
curl --request GET \
  --url https://production.runalloy.com/connectors \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-09'
```

Example response:

```json theme={null}
{
   "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.

```bash theme={null}
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:

```json expandable theme={null}
{
    "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.

```bash theme={null}
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:

```json expandable theme={null}
{
    "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.

```bash theme={null}
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:

```json expandable theme={null}
{
    "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.

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
    "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.

```bash theme={null}
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:

```json theme={null}
{
  "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](/reference/connectivity-api/connectivity-api)
* Talk to your Alloy partner manager about upcoming connectors
* Send feedback or open a support ticket

Happy building!