API tokens and ir

ir, CI and MCP clients call the Infrared API with an API token. A token acts with the roles of the person who minted it, as those roles are at the moment it's used, and what it does is recorded as theirs. When someone loses a role, their tokens lose it too.

Mint a token

Open You from your name at the foot of the rail. Under API tokens:

1. Choose the Kind. api is the usual kind.
2. Enter a Token name: lowercase letters, numbers and hyphens.
3. Choose Create API token.

Infrared shows the token once ("Copy the <name> token now"). Copy it then, because Infrared keeps only its SHA-256 hash, in the Secret infrared-api-tokens, with who minted it and when. The panel lists your tokens, each with Revoke.

You mint tokens from a session opened with Google or as the root user. A session opened with GitHub can't, and a token can't mint another token.

A telemetry token does one thing: another Infrared install sends its metrics to this one with it, at POST /v1/telemetry/write, and every series it writes is labelled with the token's Platform. Name the platform <your GitHub login>-<something>; only a platform admin may name another.

What a token acts as

Token	Acts as
Minted by a person signed in with Google	That person, with the roles their Workspace groups, address and linked GitHub login give them now. While Google Workspace reports them suspended, every call is refused.
Minted by the root user	The root user: a platform admin.
The chart's, such as mcp	A platform admin. These tokens have no owner.

A token can't do what needs a session: install a license, change the allowed domains, or change what Access holds.

Revoke a token

Revoke your own tokens on You. A platform admin revokes anyone's in Access → People, or the root user's in Access → Break glass. A revoked token stops working at once, and so do sign-in links made with it. Removing a person in Access leaves their tokens, so revoke those too.

Through the API, GET /v1/auth/tokens lists each token's name, owner and when it was minted, never the token itself: platform admins see every token, everyone else their own. DELETE /v1/auth/tokens/{name} revokes one.

Use ir with an API token

ir doesn't sign in through a browser, and never takes a token or a password as an argument. Give it a token from a file only you can read:

ir login --server https://infrared.example.com/api --token-stdin < ~/infrared-token

ir login --context <context> points ir at an install through its Kubernetes context: it reads the install's address from the Installation, checks the token ir saved against it, and saves the address. It reads no password, and Infrared keeps none in the cluster. With no saved token that works there, it exits with code 2 and names the ways in: sign in with Google and mint a token, or break glass with ir login --email.

ir setup run, which scripts the setup wizard, needs no password either: see Setup wizard.

Open Infrared from ir

ir open [<path>] signs a browser in with the token ir saved, so you never type a password or keep one on your workstation. It asks the API for a sign-in link, which works once, within 60 seconds, while the token exists, and opens it. The browser lands on <path>, such as /access, signed in as the token's owner:

• With one of the root user's tokens, the browser gets a root session, which Infrared records as a use of the root user. While password sign-in is off, the link lands on the sign-in page instead.
• With the token of a person who signs in with Google, the browser gets that person's session, while their domain is allowed and Google Workspace doesn't report them suspended.
• A token with no owner, such as the chart's mcp, makes no link.

ir open              # Infrared, signed in
ir open /access      # Access
ir open --print      # print the link instead of opening it

Whoever opens a printed link within 60 seconds is signed in, so keep it out of logs and chats. ir open --context <context> first does what ir login --context does.