App clients

An App client is how something that is not a person calls into Kiln. A telematics feed that opens a case when a vehicle event fires, a portal that runs a flow and reads the answer, a system that asks for a document to be rendered.

It is the mirror image of a Connection. A Connection is how Kiln proves itself to somebody else’s system. An App client is how somebody else’s system proves itself to Kiln.

What a client is allowed to do

Nothing, until you say so. A client’s authority is a list of grants, and each grant is three things: an action, a kind of resource, and which resources of that kind.

The actions are render a template, run a flow, read a flow run’s state, discover what flows exist, and create a resource.

Two of those are worth a sentence on their own.

Discover is separate on purpose. Being able to run a flow does not let a client enumerate your flows or read their shape. If you want an integration to find out what is available rather than being told, that is a deliberate extra grant.

Create is necessarily broad. Every other action names the resources it applies to, but a thing that does not exist yet has no identifier to name. So a grant to create is a grant over the kind, not over particular members of it. A client that may open cases may open any case of that kind.

Credentials

A client’s secret is generated here, and you see it exactly once. It is not recoverable, not by you and not by us: only a hash of it is stored, so the value cannot be read back out of Kiln in any circumstance. If it is lost, issue another one.

A plain hash is the right shape here, which is worth saying because it would be the wrong shape for a password. The secret is machine generated with a great deal of entropy and never chosen by a person, so there is nothing to guess and no dictionary to run. The protections a password needs are protections against human predictability.

A client can hold more than one secret at a time. That is what makes rotation safe: issue the new one, move the integration across, and revoke the old one when you have seen it stop being used. There is no window in which the integration has no working credential.

Note the contrast with tenant secrets, which are the credentials Kiln uses to reach outward. Those hold one value per name and have no overlap window. The direction of the arrow changes what is possible.

How a call actually works

The client exchanges its secret for a short-lived access token, then sends that token on each request. The token is signed, carries the client’s grants as they stood when it was issued, and is checked on arrival without a lookup.

A client may ask for less authority than it holds, and get it. It may not ask for more: a request for a scope the client does not hold is refused as an invalid scope rather than quietly narrowed, so a misconfigured integration fails loudly at the point of the mistake.

The limit to plan around before you revoke anything

A token is self-contained, so revoking a secret does not stop tokens that have already been issued. They keep working until they expire.

Revoking stops anybody minting new tokens. A token already minted keeps the access it carries until it expires, so revocation sets the ceiling on the damage rather than ending it instantly.

A token lasts twelve hours by default. A client may be configured with its own lifetime, up to a maximum of thirty days, and a long one is a deliberate choice somebody made rather than something that happens by itself.

Which makes the lifetime you configure the single most useful decision on this screen. Twelve hours is the default for that reason. Raise it only where an integration genuinely cannot re-authenticate, and choose the number knowing it is how long a leaked token stays useful.

An issued token runs to its expiry. Revoking the secret, clearing the grants and deleting the client all stop new tokens rather than existing ones. The check on arrival is a signature and an expiry and nothing else, with no lookup, which is the design decision that makes it fast. A token that has been issued is good until it expires.

That makes the lifetime the whole of your control, which is the reason to choose it deliberately rather than accept the maximum because an integration asked.

If you need a way to stop an integration faster than its token expires, the only lever that exists today is at the other end: change what the credential is allowed to do in the system being called, or block the caller upstream.

What it is not

It is not a user account. A client has no roles, is not a member of your tenant in the sense a person is, and cannot use the builder. Its authority is only the grants on it.

It is not how you give a person access. A person is invited to the tenant and holds roles.