API key (HTTP)

A key, a bearer token or a username/password pair, presented by the HTTP request node.

An API key connection stores a secret that the HTTP request node presents to an outside service: an API key in a header, a bearer token, a username and password, or a key passed as a URL parameter. It is the way to call any REST API that has no dedicated integration.

The secret is encrypted as soon as it is saved and never comes back out: neither the API, nor the Connections screen, nor a workflow graph can read it again. A workflow only carries the connection's identifier; the server applies the secret to the request at call time, underneath the node, so its value never appears in step data, run details or logs.

At a glance

• Identifier: http_api_key
• Family: Service
• Set up by: A member (personal) or an administrator (shared with the organisation)
• Authentication: API key or token
• Credential type: http_generic

Before you start

• The secret itself, created in the outside service's console, and the way that service expects to receive it (which header, which parameter name).
• Decide the scope. A Personal connection is visible and usable only by you. An Organisation connection is used by the whole organisation, but only an administrator can create, rename or delete it.
• An encryption key (ENCRYPTION_KEY) configured on the instance; without it, no secret can be stored. See environment variables.

The four kinds

Pick the kind the outside API documents. Each one has its own fields, and the server applies it like this:

Kind (as shown in the form)	Fields	Sent as
API key (header)	Header name (suggested: X-API-Key), Value	a header <Header name>: <Value>
Bearer token	Token	Authorization: Bearer <Token>
Username and password	Username, Password	Authorization: Basic … (HTTP Basic, username and password encoded in base64)
URL parameter	Parameter name (suggested: api_key), Value	a query parameter ?<Parameter name>=<Value> added to the request URL

URL parameter

A key passed in the URL shows up in the called service's logs, and in those of any proxy on the way. Use URL parameter only when the API offers nothing else.

Limits: a name of 1 to 80 characters; header and parameter names up to 128 characters; secrets up to 4,096 characters; usernames up to 256 characters.

Add the connection

1. Open Connections, click Add a connection, then Connect on the API key (HTTP) card. The New API key form opens.
2. Name — what you will read in a node's picker, e.g. "Billing API — production".
3. Scope — Personal or Organisation. The Organisation option is offered to administrators only.
4. Kind — one of the four kinds above, then fill in its fields. Secret fields are masked and never shown again after creation.
5. Click Create the connection.

The connection then appears in the Services family of Connections, with its name, its kind and its scope. There is no test button for this kind of connection: the first run of the HTTP request node is the test.

Use it in a node

In the HTTP request node, choose the connection in the Authentication field. It is optional: leave it empty for a public API.

• The connection takes precedence over a header of the same name typed by hand in Headers: choosing a connection is the more explicit intent.
• At every request, the server checks that the connection still exists, is active, and is either yours or the organisation's. If not, the step fails permanently instead of leaving without authentication.
• The Authentication field cannot contain a {{ }} expression: a connection is never chosen by the content of an email.
• When a step is simulated (see test runs), the secret is not decrypted; the run details only name the connection that would have been used.

Rename, replace or delete

• Rename — the Rename button on the connection's row. Only the name changes; the secret is kept.
• Replace the secret — the screen does not edit a secret: delete the connection and create a new one, then select it again in the nodes that used it. Through the API, PUT /api/v1/credentials/:id with a data object replaces the whole secret (all the fields of its kind must be sent again).
• Delete — the Delete button, then confirm. The secret is erased for good. Deletion is refused while a published workflow uses the connection: the screen lists the workflows concerned. Unpublish them, or point them to another connection, then delete.

Organisation connections can only be renamed, replaced or deleted by an administrator.

Network protections

The HTTP request node only reaches the public internet. Whatever the connection, the server refuses:

• any scheme other than http and https, and any port other than 80 and 443;
• URLs that embed a username or password (https://user:pass@host/);
• private, loopback, link-local, shared (CGNAT), multicast and reserved addresses, including the cloud metadata address 169.254.169.254 — in IPv4 and IPv6. The check applies to the address actually connected, which defeats DNS tricks that resolve a public name to an internal address.

Redirects are followed manually, up to 5, and every hop goes through the same checks. When a redirect leads to another host, the Authorization, Cookie and Proxy-Authorization headers are not forwarded to it.

A refused request makes the step fail permanently with the code http_blocked; replaying it would not make it allowed.

Common errors

Code or message	Cause	What to do
credential.admin_required — Only an admin manages an organisation connection.	A non-administrator tried to create, rename or delete an Organisation connection.	Ask an administrator, or create a Personal connection.
credential.in_use — Used by a published workflow: unpublish it or change its connection before deleting.	A published workflow references the connection.	Unpublish the listed workflows or change their connection, then delete.
credential.not_found — This connection does not exist (any more).	Deleted, or it belongs to another member.	Refresh the page; recreate the connection if needed.
credential.bad_request	A field is missing, too long, or does not belong to the chosen kind.	Correct the form.
credential.encryption_disabled — This instance cannot store secrets: the encryption key is missing.	ENCRYPTION_KEY is not configured.	Ask the instance administrator to configure it.
node_invalid_param — the configured credential cannot be used	At run time, the connection chosen in the node was deleted, is no longer active, or is a personal connection of another member.	Choose a valid connection in the node's Authentication field and publish again.
http_blocked	The URL, port, or resolved address is refused by the network protections.	Call a public address on port 80 or 443.
http_error_status — The HTTP response carries an error status.	With Fail on error response on (the default), the outside service answered with a status of 400 or more — for example 401 or 403 when it rejects the key.	Check the secret, the kind, and the header or parameter name the service expects.

Nodes that use this connection

• HTTP request — http.request