Data & connectionsGuide

API (HTTP) connections

An API (HTTP) connection holds the two things every call to one API repeats: where it lives and how you sign in. The HTTP Request step of a flow points at the connection, writes only the path, and the platform adds the address and the credential — which is kept as a secret variable, never inside the flow.

8 min readBefore this: Integrations, What a flow isOpen in Waiso

What you will learn

Create an API (HTTP) connection with the right sign-in
Know which secret variables each sign-in creates
Connect an OAuth2 API on its own sign-in page
Call the connection from the HTTP Request step, or import a cURL command

What the connection does

Without a connection, an HTTP Request step needs the full address and every header on every step — and a token typed into a header would be saved in the flow in clear. With one, the step’s address can be relative (/orders/42), the sidebar shows Relative to https://api.example.com, and the worker adds the sign-in header (or query parameter) at the moment it sends the request. The run records never contain the credential.

The HTTP Request step at the top of the flow uses a saved connection; the steps under it read its answer.

The connection lives on the project’s Integrations page, in the Services group, beside databases, storage and AI providers. One connection can serve any number of steps and flows; rotating its key is one edit, and every step picks up the new value on its next run.

Create the connection

Open the dialog
On Integrations, click Add integration and pick API (HTTP) — “Any REST API, with its sign-in”.
Name it and set the base address
The Name (for example shop-api) also names its variables. Base address must start with http:// or https://; steps write paths relative to it.
Choose the sign-in
Under Sign-in pick None, API key, Bearer token, Basic or OAuth2, and fill the fields that appear (table below).
Confirm the variables
Saving first shows Variables this connection creates with the exact names. Click Confirm and save. If a name is taken, the save waits until you rename the connection.

Sign-in	What you fill	What each request gets	Secret variable
None	Nothing	Nothing added	—
API key	Send it in Header or Query, the header or parameter name, the key	`X-Api-Key: …` by default, or `?api_key=…`	`HTTP_SHOP_API_API_KEY`
Bearer token	Token	`Authorization: Bearer …`	`HTTP_SHOP_API_TOKEN`
Basic	Username, Password	`Authorization: Basic …`	`HTTP_SHOP_API_PASSWORD`
OAuth2	Authorization address, Token address, Client ID, Client secret, Scopes	`Authorization: Bearer …` with a fresh access token	`…_CLIENT_SECRET` + `…_REFRESH_TOKEN`

The names follow the rule every connection uses: HTTP_ plus the connection name in capitals, with every run of other characters turned into one _, then the field. The username of Basic and the client ID of OAuth2 are not secrets, so they stay in the connection itself.

Connect an OAuth2 API

OAuth2 APIs never hand you a fixed token: a person signs in on the API’s own page and allows access. Waiso keeps the long-lived refresh token that comes back and turns it into short access tokens as steps need them.

Register the redirect address
With OAuth2 chosen, the dialog shows a Redirect address with Copy. Register it in the API’s app settings, where you also get the client ID and secret.
Save, then Connect
Fill the addresses, client ID, client secret and scopes (separated by spaces) and save. Open the connection again and click Connect: you sign in on the API’s page and come back with Connected.
Reconnect when asked
If the API revokes the access, steps fail with oauth_reconnect_required until someone clicks Reconnect.

Call it from a flow

In the HTTP Request step’s sidebar, choose the connection under Connection (or No connection for a full address). Then set the method and the path, add Query and Headers rows, a Body (None, JSON, Form, Text or File), and how to read the answer. The step’s output is { status, headers, body }; the next steps bind to body’s fields. The built-in steps topic covers every option, including pagination.

Import a cURL command

Import cURL opens Import a cURL command: paste the command an API’s documentation gives you and the step takes its method, address, query, headers and body. Anything that looks like a credential — an Authorization header, a -u user:password — is listed under Secrets found with Store as and a variable name, so it becomes a secret project variable instead of text in the flow.

Limits and rules

Requests leave from the worker process, never from your script’s sandbox. Every address — and every redirect hop, up to 5 — is checked: private, loopback and link-local addresses are refused with host_not_allowed unless an administrator allowed that host.
A request has 60 seconds by default; an answer over 50 MB fails with http_response_too_large; a network failure is http_request_failed.
With Fail the step when the answer is an error (4xx/5xx) on (the default), an error answer fails the step with http_status_error.
The Authorization header is dropped when a redirect leaves the API’s origin, so a credential never follows a request to another site.

ExerciseCall a public API through a connectionOpen in Waiso

Save a base address once and call a relative path from an HTTP Request step.

Before you start

A project where you can add integrations and flows

Steps

1On Integrations, click Add integration → API (HTTP).
2Name it placeholder, set Base address to https://jsonplaceholder.typicode.com, keep Sign-in on None, and save.
3Create a flow and add an HTTP Request step under Start.
4Pick placeholder under Connection, keep GET and type /todos/1 as the address.
5Click Run test and read the Answer.

Expected result

Expected outputSuccessThe answer’s status and body (headers omitted here)

{
  "status": 200,
  "body": {
    "userId": 1,
    "id": 1,
    "title": "delectus aut autem",
    "completed": false
  }
}

Hint

The sidebar line Relative to https://jsonplaceholder.typicode.com confirms the step is using the connection.

Show solution

The step joins the base address and /todos/1. A GET reads only, so Run test sends it at once; a POST, PUT, PATCH or DELETE would ask “This will really write” first.

Check yourself · 2 questions

A connection named billing uses a Bearer token. What is its variable called?

HTTP_BILLING_TOKEN, a secret variable.

Why does a step pointed at http://10.0.0.5/ fail?

It is a private address: the request is refused with host_not_allowed unless an administrator allowed that host.