Connect a system
A connection tells your Gateways where a business system is and how to sign in to it. Once you import the system's API description, its operations can become tools that agents use. You do all of this under Tools & agents → Connections.
The steps are: add the connection, give it its sign-in, import its API description (or describe its operations if it has none), then choose tools (see Tools).
Add a connection
- Open Tools & agents → Connections and click Add connection.
- Fill in the address. See the fields below.
- Choose Called by, if your environment has a hosted Gateway: Your own Gateways, or the hosted Gateway.
- Fill in the Sign-in section (see Sign-in), then click Add connection.
| Field | What to enter |
|---|---|
| Name | A short name, like main-erp. Unique in the environment. |
| Address | The system's base URL, like https://erp.example.com. Every tool call goes to this address, whatever the API description says. No user name, query or # part. |
| Allowed hosts | The hosts the Gateway may contact for this connection, comma-separated. Leave it empty to allow only the address's own host. If you fill it in, include the address's host too, plus any other host the sign-in needs, such as an OAuth2 login server. |
| Timeout (ms) | How long the Gateway waits for the system, from 1,000 to 60,000 milliseconds. The default is 10,000. A tool's own timeout can be shorter (see Tools). |
Which Gateways call it
- Your own Gateways means every Gateway in your network in this environment can call the system. Use it for internal systems.
- A hosted Gateway (shown as
<name> (hosted by Gatelion)) means only that Gateway calls it. The system must be reachable on the internet. The connection's row then says Called by Gatelion's hosted Gateway.
You choose this once, when you add the connection. It decides how secrets are handled, as described next.
Sign-in
Under How the Gateway signs in, choose one of:
| Option | What the Gateway sends | What you fill in |
|---|---|---|
| API key | The key in a header or a query parameter. | Send the key in (A header or A query parameter), the Header name (default X-Api-Key) or Parameter name (default api_key), an optional Prefix for headers (text sent before the key, like ApiKey ), and the key. |
| Bearer token | Authorization: Bearer <token>. | The token. |
| Username and password | HTTP Basic authentication. | The username and the password. |
| OAuth2 client credentials | A token it fetches from your login server, then sends as a bearer token. | Token URL (its host must be in Allowed hosts), optional Scopes (separated by spaces), optional Audience, Send the client id and secret (As HTTP Basic (most providers) or In the form body), and the client id and secret. |
| No sign-in | Nothing. | Nothing. |
How you give the secret values depends on which Gateways call the system.
On your own Gateways: secret names
For a connection called by your own Gateways, you never type a secret into the console. Each field asks for a secret name instead, for example API key secret name ERP_API_KEY. A name is 2 to 64 characters: capital letters, digits and _, starting with a letter.
The value lives only on each Gateway's machine, in the Secrets section of its settings file:
"Secrets": {
"ERP_API_KEY": "<the API key>",
"ERP_CLIENT_SECRET": { "Value": "<the client secret>", "AllowedHosts": [ "login.example.com" ] }
}
With AllowedHosts, the Gateway sends that secret only to the hosts listed. Restart the Gateway after editing the file. See Install a Gateway.
Every Gateway in your network that calls the connection needs the same names in its own settings file.
To change the sign-in later, click Change sign-in on the connection's row, then Save sign-in. Gateways use the new sign-in after their next sync.
On a hosted Gateway: sealed values
For a connection called by a hosted Gateway, you type the actual values. Your browser encrypts (seals) each value before sending it, for this connection and its allowed hosts only. Gatelion's servers store only the encrypted value, and only the hosted Gateway can open it.
- Sealed values are never shown again, not even to admins. The Sign-in column shows
key: sealed. - To change the sign-in, click Change sign-in and enter all the values again. Before you save, the console lists the addresses the secret will be usable for. Tick These are my system's addresses only if you recognise them all.
- Any change to the sign-in settings means re-entering the values: the old sealed values are tied to the old settings.
Import the API description
Gatelion builds tools from your system's OpenAPI description. On the connection's row, click Import API description.
- Choose the Description: An OpenAPI file (then choose the file) or Paste OpenAPI (then paste the document).
- Choose the System key, like
erp. Every tool id from this connection starts with it, for exampleerp.purchase_orders.create. It's 2 to 31 lowercase letters, digits or_, starting with a letter. - Click Preview. The console lists each operation it found, its request (method and path), its risk, and what would change.
- Click Import if the preview looks right, or Back to change something.
What's accepted:
- OpenAPI 3.0 or 3.1, as JSON or YAML. Swagger 2.0 documents are refused; convert them to OpenAPI 3 first.
- Up to 2 MB and 500 operations.
- Operations Gatelion can't turn into a tool, for example because their arguments can't be checked strictly, are marked Not supported with the reason.
Importing doesn't give agents anything yet. Next, choose which operations become tools under Tools → Add tools. See Tools.
You can add x-gatelion-* extensions to your description to set a tool's risk, timeout, response size, approval view and more. See OpenAPI extensions.
If your API has no OpenAPI description
Many APIs only have documentation pages, a Postman collection, or example curl commands. Describe their operations in the console instead. Gatelion turns your description into an OpenAPI document and imports it, so the preview, risks, tool versions and approval rules all work the same way.
On the connection's row, click Import API description, then choose Describe the operations as the Description, and choose the System key.
Add operations
Add each request an agent may make, in any of three ways:
- Add operation: fill it in by hand.
- Import from Postman: choose a collection exported from Postman as Collection v2.1. Each request becomes an operation, folders included.
- Paste a curl command: paste one command, for example from your API's documentation or your browser's Copy as cURL, and click Add the operation. It's only read, never run.
For Postman and curl, the console lists what it left out and why, under Check what was read. It guesses each field's kind from the sample values, so check each operation it added before you import.
For each operation:
| Field | What to enter |
|---|---|
| Name | What it does, like Create order. Agents and approvers see it. |
| Tool id | Made from the name, like create_order, so the tool is <system key>.create_order. It can't change once imported, because a different id is a different tool. |
| Method and Path | The request, like POST and /customers/{customer_id}/orders. The method is GET, POST, PUT, PATCH or DELETE. The path comes after the connection's address. Write each value the agent fills in as {name}. Path parameters then appear on their own, always required. They're identifiers by default; you can make one text or a whole number instead. |
| Risk | Default follows the method: GET is read, DELETE is high, anything else is write. Only a GET can be a read. |
| Description | Optional. Agents see it, so say when to use the operation. |
| Query parameters, Headers, Body fields | Each has a name, a kind and whether it's required. Text and identifiers can also list their allowed values. Body fields are sent as one JSON object. A GET has no body. |
| Response fields | Optional. If the answer is a JSON object, the agent sees only these fields. Leave it empty to pass the whole answer. Fields named like secrets, such as access_token, are always hidden. |
The kinds:
| Kind | Agents send | Use it for |
|---|---|---|
| Text | Any text, or one of the allowed values. | Names, notes, statuses. |
| Identifier | An id or code, checked so that look-alike characters from other scripts can't pass as it. | Order numbers, SKUs, customer ids. |
| Whole number | An integer. | Quantities, pages. |
| Decimal number | An exact decimal, like "1500.25", sent to your API as a JSON number. | Amounts and prices, which policies compare exactly. |
| Yes / no | true or false. | Flags. |
| List of text | A list of text values. | Tags. Not for path parameters or headers. |
Headers are only for values the agent chooses. Credentials such as Authorization or an API key header can't be described: the connection's sign-in sends them. Postman and curl imports leave them out for that reason.
Nested JSON, such as an object inside the body, can only be described in an OpenAPI file. Postman and curl imports leave nested fields out and say so.
Preview, import and edit
Click Preview, then Import, as for an OpenAPI file. The connection then shows Described here, and its button becomes Edit operations.
To change the API later, click Edit operations, change, add or remove operations, then preview and import again. Each save replaces the whole description: an operation you remove is Removed, and its tool is switched off. The rules in Re-import a changed description apply.
Example
Take a public test API without an OpenAPI description, JSONPlaceholder. Its connection's address is https://jsonplaceholder.typicode.com, with No sign-in. Then describe:
| Name | Method and path | Fields |
|---|---|---|
| Get post | GET /posts/{id} | Path parameter id, a whole number |
| List comments | GET /comments | Query parameter postId, a whole number |
| Create post | POST /posts | Body fields title (text, required), body (text, required), userId (whole number) |
Or paste this command and adjust what it reads:
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H 'Content-Type: application/json' \
-d '{"title": "Hello", "body": "First post", "userId": 1}'
Re-import a changed description
When your system's API changes, click Re-import description on the connection's row and import the new document the same way. The preview marks each operation New, Changed, Unchanged, Removed or Not supported.
- Each Changed operation that's already a tool gets a new tool version.
- A tool whose operation was Removed is switched off.
- New operations aren't tools until you add them.
- The system key can't change once the connection has tools.
Private networks
A Gateway refuses to reach loopback, private and link-local addresses unless that range was allowed on it. This keeps a mistaken or tampered connection from reaching other systems in your network.
- Your own Gateways: the allowed private ranges are set on each Gateway, when you install it or in its settings file as
AllowedPrivateNetworks. If a tool call fails withtarget_blocked, add the system's range there. See Install a Gateway. - Hosted Gateways can't reach private addresses at all.
The Gateway checks the address it actually connects to, and never follows redirects.
Tell it who each call is for
Each connection's Sign-in column has a switch, Tell it who each call is for. When it's on, every call carries a short-lived signed header saying which person or customer the call is for, so your system can check it. Gateways start sending it after their next sync.
Turning it on doesn't change the sign-in, and sealed values stay valid. A Gateway too old to send the header doesn't get that connection at all until you upgrade it. See Verify the identity header.
When sign-in fails
If the Gateway can't sign in, nothing is sent to your system and the call fails with a definite error, never an uncertain one. Common codes:
| Code | Meaning |
|---|---|
credential_missing | The Gateway has no secret with the name the connection gives. |
credential_not_allowed_for_host | The secret is bound to other hosts. |
token_unavailable, token_request_refused, token_response_invalid | The OAuth2 token request failed, was refused, or got an answer the Gateway couldn't use. |
See Error codes for the full list.
Related: Tools · Gateways · OpenAPI extensions
Still stuck? Contact support from the console.