What the agent does
The agent reads how sessions work today before adding a second credential. In an API like launchbadge/realworld-axum-sqlx, Cargo.toml pins axum 0.3.4, sqlx 0.5 with the postgres, uuid and time features, jwt 0.15 with hmac and sha2, argon2 0.3 and rand 0.8, and clap reads DATABASE_URL and HMAC_KEY into Config in src/config.rs. src/http/extractor.rs holds the whole scheme: AuthUser parses Authorization: Token <jwt>, verifies it with HMAC-SHA-384 over hmac_key, checks exp, and to_jwt issues a token that lasts DEFAULT_SESSION_LENGTH, two weeks. src/http/users.rs issues it from POST /api/users and POST /api/users/login and re-issues it on every GET /api/user, and a long comment in the extractor already says that stateless JWTs cannot be revoked and that the authors moved to stored sessions elsewhere. src/http/error.rs maps Error::Unauthorized to 401 and Error::unprocessable_entity to the Realworld 422 body, and ResultExt::on_constraint turns a unique-violation into one of those. The schema lives in migrations/: 1_setup.sql creates the uuid-ossp extension, set_updated_at() and trigger_updated_at(), and a case_insensitive collation; 2_user.sql creates "user" with user_id uuid default uuid_generate_v1mc(), unique username and email, password_hash, created_at and updated_at; main.rs runs sqlx::migrate!() at startup.
The change follows the files' own conventions. A new migration, named with a Unix timestamp as the migrations/README.md says to do after the bootstrapping set, creates refresh_token with refresh_token_id uuid primary key default uuid_generate_v1mc(), user_id uuid not null references "user" on delete cascade, token_hash text unique not null, expires_at timestamptz not null, revoked_at timestamptz, created_at and updated_at, and ends with select trigger_updated_at('refresh_token') like the other tables. In src/http/users.rs the User response gains refresh_token: Option<String> with skip_serializing_if = "Option::is_none", filled on registration and login only, so GET /api/user and PUT /api/user keep answering exactly the Realworld shape. A new src/http/refresh.rs module, mounted from api_router() in src/http/mod.rs beside users::router(), generates the token from 32 bytes of rand::thread_rng() encoded base64url, stores only its SHA-256 (from the sha2 crate already in the tree), and serves POST /api/users/refresh: it hashes the presented value, loads the row with sqlx::query!, answers Error::Unauthorized when it is missing, expired or revoked, and on success sets revoked_at on the old row and inserts a new one in a transaction, returning the usual UserBody<User> with a fresh AuthUser::to_jwt and the new refresh token. A presented token that is already revoked revokes every live token for that user, so a copied token ends both sessions. The refresh lifetime is a constant beside DEFAULT_SESSION_LENGTH, and the access token's two weeks are left alone and mentioned in the pull request as the obvious next change.
Compiling needs a database, which the agent sets up the way .github/workflows/rust.yml does: sqlx::query! checks every query against DATABASE_URL at build time and the repository has no offline query data, so it starts PostgreSQL in the sandbox, installs sqlx-cli with the postgres feature, runs sqlx db setup, then cargo build and cargo test. Because the crate has no tests of its own, it writes tests/refresh.rs against a running server: register, log in, call /api/users/refresh, use the returned JWT on GET /api/user, present the old refresh token again and expect 401, and present an expired row inserted straight into the table and expect 401. Then it runs the check CI runs: cargo run in the background and the Realworld Postman collection from the pinned abonander/realworld ref through run-api-tests.sh with APIURL=http://localhost:8080/api, which still passes because every field the spec defines is unchanged.
The agent does not change AuthUser, its header scheme or the HMAC algorithm, does not touch profiles.rs or articles/, and does not edit the four existing migrations, which sqlx::migrate! would refuse at startup once their checksums changed. .env.sample gains nothing, since the refresh lifetime is code rather than configuration, and Cargo.toml gains at most base64 for the token encoding.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add refresh tokens to this Axum API and open a pull request. Read Cargo.toml, src/config.rs, src/main.rs, src/http/mod.rs, src/http/error.rs, src/http/extractor.rs, src/http/users.rs, migrations/1_setup.sql, migrations/2_user.sql, migrations/README.md, .env.sample and .github/workflows/rust.yml first. Add a timestamp-named migration creating refresh_token with refresh_token_id uuid default uuid_generate_v1mc(), user_id referencing \"user\" on delete cascade, token_hash text unique, expires_at, revoked_at, created_at and updated_at, and call trigger_updated_at on it. Add refresh_token to the User response, filled on registration and login only. Add src/http/refresh.rs with POST /api/users/refresh, mounted from api_router, that generates a 32-byte random token, stores only its SHA-256, refuses missing, expired or revoked tokens with Error::Unauthorized, rotates on success in one transaction, and revokes every live token for the user when a revoked token is presented. Keep the refresh lifetime as a constant beside DEFAULT_SESSION_LENGTH and do not change AuthUser, the Token header scheme or any existing migration. Start PostgreSQL, run sqlx db setup, cargo build and cargo test, add tests/refresh.rs covering login, rotation, reuse of the old token, and expiry against the running server, and run the Realworld Postman collection the way rust.yml does. Put the test and collection output in the pull request description.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request with one new migration, src/http/refresh.rs, tests/refresh.rs, and changes to src/http/mod.rs, src/http/users.rs and Cargo.toml with its lock file. The description shows the cargo test output for the new integration tests, the Newman summary from the Realworld collection, and a curl exchange: a login answering token and refresh_token, a refresh answering a new pair, and the old refresh token answering 401. The session keeps the sqlx db setup output and every build, and GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file.
On a repository with this rust.yml, the pull request's job sets up the database with sqlx-cli, builds, runs the tests and runs the collection against cargo run, so a query the macros reject or a response field the spec does not expect fails there before merge.
A reviewer checks the refresh lifetime against how long a session should outlive its password, that only the hash reaches the token_hash column, that the rotation and the revocation happen in one transaction, and whether they now want to shorten DEFAULT_SESSION_LENGTH, which the pull request leaves at two weeks and names.
Run it on every new Axum service with JWT auth
Every service that copies this extractor inherits two-week stateless tokens, so start one run per repository that has it: a script that reads GET /o/{org}/github for the installation's repositories, or a handler that receives GitHub's repository webhook, calls POST /o/{org}/sessions with this body and the repository URL in resources, with a request_id per repository so a retry returns the run already started.
Give the key a webhook_url and Rush POSTs run.completed, run.failed or run.cancelled when each turn ends, signed per Standard Webhooks, with data.session_url to read for the pull request. A key runs at most max_concurrent sessions at once, 4 by default, but a batch over many Axum services can be sent in one go, since requests past that number answer 202 with status: "queued" and start, oldest first, as slots free.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The dangerous path in a refresh scheme is the one nobody tries by hand: a token presented after it was rotated. The agent writes that case as a test and runs it against the real server, in a sandbox where PostgreSQL is up because the sqlx::query! macros will not even compile without it, and the Postman collection, the cargo test output and the curl lines all stay on the session, so the pull request shows the 401 on reuse rather than promising it.
The result arrives as a pull request whose checks mirror what the agent already ran, not as a design note. The same request body applies to every Axum service a team owns, each in its own sandbox, and the sandbox parks with its target/ directory warm when the turn ends, so shortening the access token or moving the lifetime into Config is a follow-up on the same session rather than another full build.
Frequently asked questions
Does the access token change?
No. AuthUser, the Token header scheme, the HMAC-SHA-384 signing and the two-week DEFAULT_SESSION_LENGTH are untouched, so every existing client keeps working. The pull request notes that a shorter access token is the usual next step once refresh exists and leaves that to the reviewer.
Why store a hash instead of the token?
Because the table would otherwise be a list of live sessions for anyone who reads a backup. Storing the SHA-256 lets the handler find the row from the value a client sends while the stored column is useless on its own, the same reasoning password_hash already follows with Argon2.
Why does the build need a running database?
The repository uses sqlx::query! and query_as!, which check each SQL statement against DATABASE_URL at compile time, and it has no offline query data checked in. The agent does what rust.yml does: start PostgreSQL, run sqlx db setup, then build. The new queries get the same checking.
What happens when a refresh token is stolen?
Rotation means the thief and the real client each hold a token only one of which is live. When the stale one is presented, the handler revokes every token for that user, so both must log in again. tests/refresh.rs covers that path.
Will the Realworld Postman collection still pass?
Yes. The collection checks the fields the spec defines on each response, and the change adds refresh_token on registration and login without renaming or removing anything, and adds a route the collection never calls. The agent runs it against the built server before pushing.