Connections

A Connection is how a flow reaches a system that is not Kiln. Your loan management system, a vehicle data API, a portal your operations team already signs in to. You author it once, name it, and flows refer to it by that name rather than carrying an address and a key of their own.

It holds two sorts of thing, and the difference between them is the whole design.

Config values are not secret. A base URL, a timeout, a flag, an account number. They live in the Connection document, you can read them on screen, and they are edited like any other field.

Secret references are not values. A reference names a secret; the secret’s value is never in the Connection, never on screen, and never sent to the browser. It is resolved backend only, at the moment of the call.

So what an author reads, edits, copies and hands to a colleague is the reference. Nobody working in the builder handles the credential itself.

Where the secret actually lives

Two tiers, and you pick per reference.

Tenant secrets are yours. They sit in your own scope, encrypted at rest, and are decrypted only for the call that needs them. They are managed under Settings, Secrets, separately from any Connection, because a secret is not owned by the Connection that uses it. One key can be attached to several Connections.

Platform secrets are shared across Kiln, for services that are the same for everybody rather than particular to you.

If you are not sure which you want, you want a tenant secret.

The three ways a Connection authenticates

Most APIs fall into one of these. You are picking the shape of the handshake, not writing it.

A static key on every request. The simplest. A secret reference is injected as a header, the same header on every call.

Token exchange, for an API that swaps a long lived key for a short lived token. You give Kiln the token endpoint, whether the key travels as a header or as a body field, which reference holds it, and where in the response the token is. At run time Kiln mints the token and sends it as a Bearer on the actual call. The long lived key never reaches the system you are calling.

Session login, for an API that expects you to sign in and then send cookies back, which is how a great many internal portals work. You give Kiln the login address and which references hold each field of the login, and it captures the session cookies and replays them on every call. If the API needs a page visited first to issue a cross-site request token, there is a step for that, and the double submit of that token is handled for you.

The captured session lives only for that run. A credential used to log in is never also sent as a header on the calls that follow.

Both of the second two refuse a token or login address that is not https. There is no setting to allow cleartext.

Testing it before a flow depends on it

A Connection has its own test, which sends a request you nominate, using this Connection’s real credentials, exactly as a flow would.

The path you test is always relative to the Connection’s own base address. Absolute addresses are refused, when you save the test and again when you run it. That is deliberate and it is the same reasoning as the boundary below: a test carries live credentials, so being able to aim it at any address of your choosing would be a way to send them somewhere they do not belong.

The boundary worth understanding before you grant access

Whoever can edit a Connection can direct its credentials at a system they choose. The address a token is minted from, and the address a login is posted to, are both fields on the Connection.

So editing a Connection carries the same weight as holding the credential itself, even though the value is never displayed. Hiding the value protects against the everyday things: a mistake, a screenshot, somebody reading over a shoulder.

Give Connection editing to the people you would trust with the credentials, and the separation takes care of the rest. That is the same judgement you already make about who holds production access anywhere else.

Changing a key

Rotating replaces a secret’s value in place. Any Connection referring to it picks up the new value on its next run, with no edit to the Connection.

One thing to plan for: there is no overlap window. The store holds one current value per name, so the moment you rotate, the old credential stops being used. Time it with whatever change the other system is making, rather than assuming the two can be valid at once.

Rotation cannot create. A name that does not exist cannot be rotated into existence. That is deliberate, and it is why rotation can be given to people who are not allowed to stand up new integrations.

Removing a secret that is still in use is refused, and the refusal names the Connections that still attach to it, so you get a list of what to detach rather than a message telling you something is in use somewhere.

What a flow sees

The flow sees the Connection’s name and its config values. It does not receive the secret values, and it cannot be written to print them.

A credential is stored as a reference, never a value. It is resolved backend only at run time, and it never enters the Connection document, the flow’s payload, or the case or instance event log.

What this does not do

It does not hold credentials for a system Kiln is not calling. A Connection is outbound. Something calling in to Kiln is an App client, which is a different surface and a different set of controls.

It does not decide which flows may use it. Any published flow in your tenant can name any Connection your tenant has. Scope a credential by what it is allowed to do in the system it reaches, not by expecting Kiln to fence it per flow.