An API key connection holds one secret that Natiq adds, as one request header, to calls your flows make to your own API. It is how an HTTP request step or an AI agent's Lookups authenticate, and it is the other direction from the credentials in Authentication: here Natiq calls you.

What it guarantees

Guarantee	Detail
One host	The key is sent only to the host you named when you saved it. If a step's address is not https on exactly that host (port 443), the call is refused and the step fails — nothing is sent. The editor warns you.
HTTPS only	It is sent only over https, and only to port 443. An address with http or another port is refused, and nothing is sent.
Never in the flow	The flow stores only the connection's id. The key is not in the flow JSON, exports or the Flow Assistant's view of the flow.
Never in a prompt	The AI never sees the key, the address or the method of a lookup. It only fills the blanks you declare.
Write-only	The key is stored encrypted and is never shown again. To change it you enter it again.

Create one in the dashboard

1. In the Agent Builder, open a flow with an HTTP request step, or an AI Agent step. On an HTTP step choose New API key under API key; on an AI Agent, open Lookups and add a key from a lookup row.

2. Check the Host: only this address ever receives the key, for example api.shop.com. Enter it without https:// or a path.

3. Under Send the key as, choose Bearer token (Authorization: Bearer <key>), X-API-Key header, or Custom header.

4. Paste the Key and select Save key.

The summary line reads: your key goes in the chosen header of every call to the host, and nowhere else.

Field rules

Field	Rule
Name	Defaults to <host> API key. Fixed after creation, so lookups using it keep working.
Host	A lowercase domain name with at least one dot, such as api.shop.com. No scheme, port, path, or IP address.
Header name	Letters, digits and -, up to 64 characters. Host, Cookie, Content-Length, Transfer-Encoding, Connection and any Proxy- header are refused.
Prefix	Optional, up to 64 printable characters, kept exactly, including a trailing space: Bearer is the preset.
Key	12 to 2048 printable characters, no line breaks, no spaces at either end.

The server validates the same rules and also knows the public-suffix list, so a host the browser accepts can still be refused.

Use it

In an HTTP request step, pick the key under API key. The step's address must name the key's host. The step's own sign-in, proxy and redirect options are then hidden because the key takes care of sign-in.

In an AI Agent's Lookups, each lookup is a fixed request:

Part	Detail
Address	https://…, a plain domain host (no IP), under 2000 characters, no user name or password in it, no #fragment, path and query plain ASCII.
Blanks	Single braces in the path, query or body, like https://api.shop.com/orders/{order_id}. Names use lowercase letters, digits and _, starting with a letter (at most 40 characters). Blanks cannot be in the host.
Method	GET, POST, PUT, PATCH or DELETE; only POST, PUT and PATCH take a body. Anything other than GET can change data in your system, and the row says so. Describe exactly when the AI may call it.
Limit	Up to 10 lookups per AI Agent step.

The model sees a lookup's id, its description and the blanks, nothing else. Publishing shows a card listing the hosts the agent can call and whether a key is sent.

Over the API

Connections are an ordinary REST resource, under the Authentication token of a user with builder.bots:write (builder.bots:read to list connections).

Create:

curl -X POST https://api.cx.na6iq.com/api/v1/integrations/connections \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "pieceName": "natiq-api-key",
    "displayName": "api.shop.com API key",
    "authType": "CUSTOM_AUTH",
    "value": {
      "headerName": "Authorization",
      "prefix": "Bearer ",
      "secret": "sk_live_replace_me_123456",
      "host": "api.shop.com"
    }
  }'

The response describes the connection (id, displayName, host, headerName) and never includes the secret.

List the organisation's keys: GET /api/v1/integrations/connections?pieceName=natiq-api-key.

Replace the stored value and keep the id, so everything pointing at it keeps working: PUT /api/v1/integrations/connections/{id}/credentials with { "authType": "CUSTOM_AUTH", "value": { … } }. Send the whole value again, secret and prefix included, because the old secret cannot be read back. The backend validates before saving, and a refusal leaves the stored key untouched.

Troubleshooting

You see	Meaning
The key is for host A, but the address calls host B	The step or lookup points at a host the key was not saved for. Fix the address or save a key for host B.
The step's URL uses http or a port other than 443	Keys go only over https on port 443. Remove the port, or drop the key.
The key no longer exists	It was deleted. Pick another, or create it again.
A lookup row says it is not an API key connection	Pick a connection of this type; other connections send no key.
Your API answers 401	Check the header name and prefix match what your API expects; replace the key if it was rotated on your side.

A different "API key" in Natiq

The organisation can also mint a key with POST /admin/api-keys, sent as X-Natiq-Api-Key to Natiq's bot webhook route. It is for sending messages in, is unrelated to this page, and is not a general REST credential. See Authentication.