Secrets

A secret is a credential your tenant holds: an API key, a password, a token that lets Kiln reach a system you already run. They live under Settings, Secrets, and Connections refer to them by name.

They are deliberately kept apart from the Connections that use them. A secret is not owned by any one Connection, so the same key can be attached to several, and replacing the key is one act rather than an edit in every place it appears.

You give a secret a name, and never see it again

This is the one thing to understand before anything else.

A secret has a name you choose and a value you set once. No screen and no API in Kiln will give the value back to you. Not the list, not the detail, not an export. The list tells you what exists, when it was set and by whom. It does not tell you what it is.

That is not a missing feature. A store you can read is a store somebody else can read, and the value only ever needs to travel in one direction: in from you, out to the system it authenticates against.

The practical consequence is worth planning for. Keep the credential wherever your organisation keeps credentials. Kiln is where you put a copy for Kiln to use, not where you look it up later.

Scope

A secret belongs to one scope and never leaves it. Your tenant’s secrets are yours, and they are encrypted at rest with the scope bound into the encryption itself, rather than merely recorded next to it. A value written in one scope cannot be decrypted from another, and that is a property of how it was encrypted rather than a check somewhere that could be got around.

Setting, replacing and removing

Three separate acts, and they are separate on purpose.

Creating a secret establishes a name that did not exist. If the name is already taken, it is refused rather than overwritten, so you cannot silently replace a working credential by re-adding it.

Rotating replaces the value behind an existing name. Every Connection that refers to that name picks up the new value at its next run, with no edit to any Connection. Rotation cannot bring a name into existence: if it does not exist, rotation is refused rather than treated as a create.

One thing to plan around: rotation has no overlap window. The store holds one current value per name, so the moment you rotate, the old credential stops being used. There is no period in which both work. Coordinate it with whatever change the other system is making, rather than assuming you can rotate first and tidy up afterwards.

Removing destroys the value outright. It is refused while any Connection still refers to the name, and the refusal names those Connections so you know what to detach rather than being told it is in use somewhere.

What a destroyed secret leaves behind

Destroying a credential is the one act here with no undo, so it leaves a record: the name, when it was destroyed, and who destroyed it. No value and no encrypted value, because there is nothing there a destruction duty would reach. It is the name you chose and a timestamp.

The record survives the name being used again. If you destroy a credential and stand up a replacement under the same name, the destruction is still on the record afterwards, because a destroy that leaves no trace is indistinguishable from a credential that never existed.

How a flow uses one

It does not, directly. A flow never names a secret and never receives its value.

A Connection refers to a secret by name, a flow refers to the Connection, and the value is resolved at the moment of the call. So the thing an author works with is two steps removed from the credential.

The part to read before granting access

Editing a Connection is equivalent, in what it makes possible, to reading that Connection’s secret values. The address a credential is sent to when authenticating is a field on the Connection, so whoever can edit one can cause the credential to be sent somewhere they can read it.

That is on the Connections page too, and it is repeated here because this is the page somebody reads when they are thinking about who should hold credentials. The secrecy of the value protects against a mistake, a screenshot and a passer-by. It does not protect against somebody who is allowed to edit Connections.

What this is not for

It is not for holding a customer’s personal information, or anything that is not a credential. It is a small store designed around never giving a value back, which makes it the wrong shape for anything you need to read.

It is not a way to give a system access to Kiln. That is an App client, which is a different surface: a secret is how Kiln proves itself to somebody else, an App client is how somebody else proves themselves to Kiln.