Create and Revoke Auth Tokens

Auth tokens are how anything that is not a person authenticates to Stairwell: the REST APIs, the swell CLI, and the forwarder. Admin users manage them from Settings.

There are two types and they behave differently in ways that matter:

That second row is the one to internalize. A forwarder token is not tied to you. Your account being disabled tomorrow does not stop it, which is correct behavior for a fleet and surprising the first time somebody checks.

How do I create one?

1. Sign in at app.stairwell.com.
2. Select the Settings icon in the left menu.
3. Open the Auth tokens tab under Organization.
4. Select Generate Token.
5. Choose API/CLI token or File Forwarder token.
6. Give it a name.
7. Select Generate.
8. Copy the value now. It is not shown again.

Name it for what it does, not for who made it. Tines-integration-prod and forwarder-dc-east are names somebody can act on a year from now. mike-token-2 is not, and the practical consequence is that nobody ever revokes it, because nobody can prove what it would break. Naming is the whole of token hygiene.

How do I revoke one?

Revoking is immediate and permanent. Every script, automation, and integration using that token stops working, with no grace period.

1. Sign in at app.stairwell.com.
2. Select Settings, then the Auth tokens tab under Organization.
3. Find the token by name, or filter for it.
4. Select the ... icon under Actions.
5. Choose Revoke and confirm.

What does revoking a forwarder token leave behind?

Its Forwarder Service Account, which appears under the Users tab and is not removed with the token.

To clean up fully, revoke the token and then disable the service account. Doing only one of the two is the common half-measure, and the two halves fail differently: revoking the token stops it authenticating, while disabling the account only prevents registering new assets. See User Roles and Types.

What else should I know?

Tokens do not expire. Nothing ages one out, so an unused token stays valid indefinitely. That makes periodic review a real task rather than a formality, and it is another reason the names matter.

API/CLI tokens inherit the permissions of the user who generated them. A token made by an Admin is an Admin token. If a script only needs to read, generate its token from an account that can only read, because the token cannot be scoped down afterwards.

Scope follows the level the token was created at. See What Auth Tokens Can Access, which matters most if you manage more than one environment.

Do not confuse an auth token with a maintenance token. Maintenance tokens are environment-scoped, expire after 14 days, and exist only to authorize forwarder maintenance. See Asset Identifiers.

What should I read next?

• What Auth Tokens Can Access, for the scoping rule.
• REST APIs, for what to do with a token.
• User Roles and Types, for service accounts.