# Add Refresh Tokens to an Axum JWT API

Yes. An agent adds a stored, rotating refresh token beside the JWT an Axum API issues, a refresh route that swaps it, a SQLx migration and tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-refresh-tokens/axum/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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.

## More Axum jobs

- [Add Request Timeouts to an Axum API](https://getrush.ai/run/add-request-timeouts/axum/)
- [Add Request Tracing to an Axum API from a Linear Issue](https://getrush.ai/run/add-request-tracing/axum/)
- [Add Security Headers to an Axum API](https://getrush.ai/run/add-security-headers/axum/)

## The same job on other stacks

- [Add Refresh Tokens to a Gin JWT API](https://getrush.ai/run/add-refresh-tokens/gin/)
- [Add Refresh Tokens to an Express API That Uses jsonwebtoken](https://getrush.ai/run/add-refresh-tokens/jsonwebtoken/)
- [Add Refresh Token Rotation to a NextAuth.js App](https://getrush.ai/run/add-refresh-tokens/next-auth/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
