curl --request POST \
--url https://control.ergoly.ai/api/v1/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://control.ergoly.ai/api/v1/connections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://control.ergoly.ai/api/v1/connections"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"id": "6d5c4b3a-2918-4706-9f8e-1d2c3b4a5968",
"key": "stripe_live",
"kind": "api_key",
"type": "secret",
"scope": "org",
"workerId": null,
"clientId": null,
"internalOnly": false,
"managed": false,
"hosts": [
"api.stripe.com"
],
"description": "Billing — subscriptions, invoices and refunds.",
"provider": null,
"account": null,
"providerScopes": [],
"expiresAt": null,
"health": null,
"issuer": null,
"issuerHost": null,
"mcpEndpoint": null,
"mcpTransport": null,
"mcpTools": [],
"mcpStatus": null,
"mcpServerName": null,
"providerClientId": null,
"redirectUri": null,
"createdAt": "2026-02-01T09:14:00.000Z",
"updatedAt": "2026-02-01T09:14:00.000Z"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}Create a connection
Two shapes, told apart by app. WITHOUT it, this stores a secret: value is write-only, it goes in here and no route gives it back; give at least one host unless the key already has some — a credential no host points at is never injected by the gateway, so it would sit there doing nothing; a key already taken at the same scope is a conflict, as is a host already mapped to another connection. WITH app — a catalog slug or a tool server’s URL — this connects an app and places it: omit auth and the answer carries connectUrl, a hosted sign-in to open in a browser, with the connection pending until consent finishes and active after (poll GET /api/v1/connections/{id}); send auth.mode: "key" with the key in value and it is stored at Composio and checked with one real call, verified reporting the verdict; a tool server that takes a key names the header it goes in with auth.header (absent is Authorization, sent as Bearer <key>; any other header carries the key on its own); a tool server that takes no credential is auth.mode: "none", and gets a row and a placement with nothing stored anywhere. A placement no ework could read — instance on a Worker with no active ework for that Client, client for a Client no Worker has one for — is a conflict naming the pair, refused before a key or a sign-in reaches Composio. The check is made once, up front: an ework removed while Composio is being called can still leave the placement in place, and adding or moving a placement later is checked again at the write. connectUrl is shown once — a replay under the same Idempotency-Key withholds it — and the pasted key is never in any response. sessions says which eworks can use the app now.
curl --request POST \
--url https://control.ergoly.ai/api/v1/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://control.ergoly.ai/api/v1/connections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://control.ergoly.ai/api/v1/connections"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"id": "6d5c4b3a-2918-4706-9f8e-1d2c3b4a5968",
"key": "stripe_live",
"kind": "api_key",
"type": "secret",
"scope": "org",
"workerId": null,
"clientId": null,
"internalOnly": false,
"managed": false,
"hosts": [
"api.stripe.com"
],
"description": "Billing — subscriptions, invoices and refunds.",
"provider": null,
"account": null,
"providerScopes": [],
"expiresAt": null,
"health": null,
"issuer": null,
"issuerHost": null,
"mcpEndpoint": null,
"mcpTransport": null,
"mcpTools": [],
"mcpStatus": null,
"mcpServerName": null,
"providerClientId": null,
"redirectUri": null,
"createdAt": "2026-02-01T09:14:00.000Z",
"updatedAt": "2026-02-01T09:14:00.000Z"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docs": "<string>"
}
}Authorizations
An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, <resource>:<read|write>, where the resource is the first path segment after /api/v1/; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one.
Headers
Any unique string.
Body
CONNECT AN APP. A catalog slug (hubspot, exa) or a tool server's https:// URL. Present, the body is the app shape — placement and name are required, auth and discoveryUrl may follow, and nothing from the secret shape below may appear beside them. Absent, the body is the secret shape and key, kind and value are required.
Where the connected app may be used. Required with app. More placements can be added afterwards.
Show child attributes
Show child attributes
What to call the connected app. Required with app; unique in the organization.
How the person authenticates, with app. Omitted means a hosted sign-in.
Show child attributes
Show child attributes
With an app that is a tool server URL: its authorization server's metadata URL, when you know it. Omitted, Ergoly asks the server.
STORE A SECRET. The slug the agent and the gateway will know it by. Lowercase letters, digits, _ and -. Unique per scope. Required without app.
How the gateway injects it. Required without app. oauth is not accepted here — an OAuth account is made by the connect flow, which is the only path that can revoke it later.
api_key, secret, basic The secret itself. Required without app. WRITE-ONLY: no response on this API returns it, and there is no route that reads it back.
Which identities resolve it. Defaults to org.
org, worker, client Required when scope is worker.
Required when scope is client.
Hide it from client-tier eworks. Cannot be combined with a client scope — it would resolve for no one.
The hosts the gateway injects this credential on. At least one is required unless the key already has hosts: a credential no host points at is never injected.
A bare hostname — no scheme, path, port or wildcard.
Response
Success.
- Option 1
- Option 2
Show child attributes
Show child attributes