# Connect your own connector

Source: https://docs.vlayers.ai/reference/hosting/create-workspace-connection

`POST /v1/workspace-connectors/{name}/connections` · scope `workspace:write`

Makes a connection of a connector that has a live version. The credentials are not in this body: save each in your vault first (`POST /v1/connections`, encrypted at rest) and give its id here. `webhook` verifies what the provider sends (a signing secret, a public key or a secret token, by the connector's declared scheme); `handshakeToken` answers an unsigned subscription check (needed when the connector declares one); `primary` is what its sends and live connection sign in with (needed when it declares either). `host` is one of the hosts the connector declares (needed when it declares more than one). With an `agentId` the agent answers at once; without it the connection waits as `NEEDS_INPUT` until `POST /v1/connector-connections/{id}/bind`. The answer carries `webhookUrl`: the address to give the provider.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | path | string | yes | The connector name: the last part of `ws/<workspace>/<name>`. Example: `"telegram"` |
| `displayName` | body | string | yes | A name for this connection (1 to 120 characters). |
| `credentials` | body | object | yes | Vault ids: `webhook`, `handshakeToken` and `primary`, as the connector needs them. |
| `host` | body | string | no | Which declared host sends go to (optional when the connector declares one). |
| `authType` | body | "oauth2" \| "api_key" \| "bearer" \| "basic" \| "none" | no | How the `primary` credential is presented: `bearer`, `basic`, `api_key`, `oauth2` or `none`. |
| `credentialPlacement` | body | object | no | Where the `primary` credential goes on a request: a header, a path prefix holding `{secret}`, or a query parameter. |
| `agentId` | body | string | no | The agent that answers through the connection (optional). |

## Request

cURL:

```bash
curl -X POST "https://api.vlayers.ai/v1/workspace-connectors/$CONNECTOR_NAME/connections" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Support bot",
    "credentials": {
      "webhook": "0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",
      "primary": "0192f5c4-8b9c-7dbe-8f30-4b5c6d7e8f9a"
    }
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { webhookUrl } = await voicelayer.hosting.createWorkspaceConnection('<connector-name>', {
  displayName: 'Support bot',
  credentials: {
    webhook: '0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89',
    primary: '0192f5c4-8b9c-7dbe-8f30-4b5c6d7e8f9a'
  }
});
console.log(webhookUrl);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.create_workspace_connection(
    "<connector-name>",
    display_name="Support bot",
    credentials={
        "webhook": "0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",
        "primary": "0192f5c4-8b9c-7dbe-8f30-4b5c6d7e8f9a",
    },
)
print(result.webhook_url)
```

## Response `201`

```json
{
  "connectionId": "0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",
  "connectorId": "ws/0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45/telegram",
  "displayName": "Support bot",
  "status": "READY",
  "host": "api.telegram.org",
  "webhookUrl": "https://api.vlayers.ai/v1/connector-webhooks/ws%2F0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45%2Ftelegram/0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",
  "bound": true
}
```
