> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connections
> Store and verify per-organization credentials for platform integrations
A connection binds your organization's credentials to one platform service — for example, your Five9 Configuration Service login. Tasks never carry credentials themselves; they reference a connection by ID, and the platform resolves the credentials at runtime. Connections belong to your organization and are never visible to other accounts.
```json theme={null}
{
"task_id": "add_contact",
"task_name": "Add to dialing list",
"platform_id": "five9",
"service_id": "five9__configuration_service",
"action_id": "five9__configuration_service__add_to_list",
"connection_id": "conn_e5f6g7h8",
"parameters": { "list_name": "Outbound Q3" }
}
```
Create the connection first, then reference its `connection_id` from any task that calls that service. Built-in utility actions (like `getdialed__utils__echo`) need no connection.
## The connection object
| Field | Type | Description |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Connection identifier (e.g. `conn_e5f6g7h8`). |
| `name` | string | Human-readable name (e.g. "Five9 Production"). |
| `platform_id` | string | Platform from the [catalog](/concepts/catalog) (e.g. `five9`). |
| `service_id` | string | Service from the catalog. Must start with `platform_id + "__"` (e.g. `five9__configuration_service`). |
| `auth_method` | string | One of `basic_auth`, `oauth2`, `client_credentials`, `jwt`, `api_key`, `soap_wss`. |
| `credentials_ref` | string | Reference to where the secrets are stored. Secrets are resolved from secure storage at runtime and never returned by the API. |
| `status` | string | `active`, `expired`, or `revoked`. |
| `last_verified` | datetime \| null | When the credentials last passed a verification test. |
## Managing connections
All management endpoints require authentication and operate only on your organization's connections.
| Method | Endpoint | Purpose |
| -------- | ------------------------------ | ------------------------------------------------------------------------- |
| `GET` | `/connections` | List connections. Filter with `status`, paginate with `limit` and `skip`. |
| `POST` | `/connections` | Create a connection. Returns `201` with the created object. |
| `GET` | `/connections/{connection_id}` | Fetch one connection. |
| `PUT` | `/connections/{connection_id}` | Update a connection — a full replacement; supply all fields. |
| `DELETE` | `/connections/{connection_id}` | Delete a connection. Returns `204`. |
Creating one:
```bash theme={null}
curl -X POST "$BASE_URL/connections" \
-H "X-API-Key: $GETDIALED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Five9 Production",
"platform_id": "five9",
"service_id": "five9__configuration_service",
"auth_method": "basic_auth",
"credentials_ref": "vault://five9/prod"
}'
```
A connection's `status` is under your control — it is never flipped automatically, even when a verification test fails. Transition it explicitly with `PUT /connections/{connection_id}` when credentials expire or are revoked.
## Testing credentials
Two endpoints verify that credentials actually work against the live platform, so you can catch a bad password before a flow fails at 2 a.m. Both require an admin-role caller and complete within a 15-second budget.
`POST /connections/test` takes `platform_id`, `service_id`, `auth_method`, and a platform-specific `credentials` object (e.g. `{"username": ..., "password": ...}` for Five9 basic auth). It returns a pass/fail verdict and **persists nothing** — ideal for a "test before save" flow.
`POST /connections/{connection_id}/test` (no request body) resolves the saved connection's stored credentials and runs the same verification. On success, the connection's `last_verified` timestamp is updated.
Both endpoints return `200` with a `TestResult` body for **every** verification outcome — success, bad credentials, even a timeout. `4xx` statuses are reserved for problems with your request itself (malformed body, missing auth, unknown connection ID).
### The TestResult body
```json theme={null}
{
"success": false,
"error": "AUTH_FAILED",
"details": "Five9 rejected the supplied credentials (HTTP 401/403).",
"latency_ms": 312,
"tested_at": "2026-05-18T10:30:00Z"
}
```
| Field | Type | Description |
| ------------ | -------------- | ------------------------------------------------------------------- |
| `success` | boolean | `true` if the platform accepted the credentials. |
| `error` | string \| null | An error code (below) when `success` is `false`; `null` on success. |
| `details` | string | Human-readable diagnostic. Never contains credentials. |
| `latency_ms` | integer | Round-trip time of the verification call, in milliseconds. |
| `tested_at` | datetime | UTC timestamp of when the test started. |
### Error codes
| Code | Meaning |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_FAILED` | The platform rejected the credentials. |
| `NETWORK` | The platform couldn't be reached (DNS, TCP, TLS), or the stored secret couldn't be found. |
| `TIMEOUT` | The test exceeded the 15-second budget. |
| `RATE_LIMITED` | The platform throttled the request. |
| `PERMISSION_DENIED` | Authenticated, but not authorized for the verification call. |
| `INVALID_CREDENTIALS_SHAPE` | The `credentials` object is missing keys the platform requires (e.g. Five9 basic auth needs `username` and `password`) — caught before any network call. |
| `UNKNOWN` | Anything else, including platforms without a test handler. |
`422` and `INVALID_CREDENTIALS_SHAPE` look similar but differ: `422` means the request body itself is malformed (wrong types, missing schema fields, `service_id` not prefixed with the platform ID), while `200` + `INVALID_CREDENTIALS_SHAPE` means the body parsed fine but the credentials object lacks what the target platform needs.
## Next steps
Browse the platforms and services a connection can target.
Put a connection to work in a multi-step flow.