Service tokens

The credential a machine uses: one environment, read or write, shown once.

A service token is the credential a machine authenticates with. You mint one from Service tokens in the app, or from Integrations → Kubernetes, which also fills in the install commands around it.

Every token is scoped to one environment at Read or Write access, and carries an expiry. A second environment means a second token.

Read and write

Read lets the holder read the keys in its environment. Write includes read. There is nothing finer, because a machine credential describes what a pipeline does rather than a person’s standing in an organisation.

Every token expires

An expiry is required. The longest lifetime is set by whoever runs your orcakey.sh — a year by default, and never more than that.

Ask for longer than the maximum and the mint is refused. It is not quietly shortened, so the expiry you were given is the one you asked for.

Renewal

A token can exchange itself for a successor, by presenting itself, before it expires. The successor is a new credential with a new expiry; the one that asked is revoked in the same act, so there is never a moment with two live tokens for one consumer.

The Kubernetes connector does not renew its token. Integrations → Kubernetes mints for a year, the default maximum; before it expires, mint a replacement and update the token Secret in the cluster. The next resync picks it up.

Nothing about the successor can be wider: same environment, same access level, same name. There is no field to ask for more, so the worst a stolen token achieves is the access it already had, for longer.

Every renewal is its own audit record, naming the token it replaced. A chain renewing quietly for two years is what healthy looks like; one renewing from somewhere you do not recognise is what you are looking for.

Why expiry still matters when something renews

It does not stop an attacker holding a live token: they can renew it too. What it kills is the copy nobody is renewing — the one in an old backup, a log, a laptop that left with somebody. Those stop working on their date without anyone doing anything, and they are a large share of how credentials actually leak.

Against an attacker who does renew, the controls are different: every renewal is an audit record naming what it replaced, and a deployment can bound how long a chain runs before a person has to decide again.

Tokens that outlive the maximum

Not every consumer is a cluster. A job that runs twice a year has nothing to renew it, and an Owner can mint a token deliberately past the deployment's maximum.

It is marked long-lived wherever it is listed, because that is the point: when an expiry is years away it has stopped being a control, and somebody seeing the credential in a list is what replaces it. The same list shows when each token was last used, and says so when nothing has presented one in a month.

There is still no token without an expiry. A date that arrives is a date somebody looks at the credential again; no date is never revisited by anything except an incident.

The value is shown once

The token appears exactly once, when it is minted. orcakey.sh stores a hash of it and has no route that can produce the value again.

A token starts with orcakey_, which makes it recognisable to secret scanners and to anybody reading a log who should not be seeing one.

Revoking

Revoke a token in the app. The next request that presents it is refused; nothing is cached, so there is no window to wait out.

A connector holding a revoked token reports Unauthorised and leaves whatever it last wrote in place.