coder · BobbyHo · Aug 29, 2026
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -2115,6 +2115,10 @@ func (q *querier) DeleteAPIKeyByID(ctx context.Context, id string) error {
 	return deleteQ(q.log, q.auth, q.db.GetAPIKeyByID, q.db.DeleteAPIKeyByID)(ctx, id)
 }
 
+func (q *querier) DeleteAPIKeyByIDReturningRow(ctx context.Context, id string) (database.APIKey, error) {
+	return fetchAndQuery(q.log, q.auth, policy.ActionDelete, q.db.GetAPIKeyByID, q.db.DeleteAPIKeyByIDReturningRow)(ctx, id)
+}
+
 func (q *querier) DeleteAPIKeysByUserID(ctx context.Context, userID uuid.UUID) error {
 	// TODO: This is not 100% correct because it omits apikey IDs.
 	err := q.authorizeContext(ctx, policy.ActionDelete,

diff --git a/coderd/database/dbauthz/dbauthz_test.go b/coderd/database/dbauthz/dbauthz_test.go
@@ -360,6 +360,12 @@ func (s *MethodTestSuite) TestAPIKey() {
 		dbm.EXPECT().DeleteAPIKeyByID(gomock.Any(), key.ID).Return(nil).AnyTimes()
 		check.Args(key.ID).Asserts(key, policy.ActionDelete).Returns()
 	}))
+	s.Run("DeleteAPIKeyByIDReturningRow", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
+		key := testutil.Fake(s.T(), faker, database.APIKey{})
+		dbm.EXPECT().GetAPIKeyByID(gomock.Any(), key.ID).Return(key, nil).AnyTimes()
+		dbm.EXPECT().DeleteAPIKeyByIDReturningRow(gomock.Any(), key.ID).Return(key, nil).AnyTimes()
+		check.Args(key.ID).Asserts(key, policy.ActionDelete).Returns(key)
+	}))
 	s.Run("DeleteExpiredAPIKeys", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
 		args := database.DeleteExpiredAPIKeysParams{
 			Before:     time.Date(2025, 11, 21, 0, 0, 0, 0, time.UTC),

diff --git a/coderd/database/dbmetrics/querymetrics.go b/coderd/database/dbmetrics/querymetrics.go
diff --git a/coderd/database/dbmock/dbmock.go b/coderd/database/dbmock/dbmock.go
diff --git a/coderd/database/querier.go b/coderd/database/querier.go
diff --git a/coderd/database/querier_test.go b/coderd/database/querier_test.go
@@ -19088,6 +19088,22 @@ func TestSingleUseDeleteByIDReturningRow(t *testing.T) {
 		_, err = db.DeleteOAuth2ProviderAppCodeByIDReturningRow(ctx, code.ID)
 		require.ErrorIs(t, err, sql.ErrNoRows)
 	})
+
+	t.Run("APIKey", func(t *testing.T) {
+		t.Parallel()
+		db, _ := dbtestutil.NewDB(t)
+		ctx := testutil.Context(t, testutil.WaitLong)
+
+		user := dbgen.User(t, db, database.User{})
+		key, _ := dbgen.APIKey(t, db, database.APIKey{UserID: user.ID})
+
+		deleted, err := db.DeleteAPIKeyByIDReturningRow(ctx, key.ID)
+		require.NoError(t, err)
+		require.Equal(t, key, deleted)
+
+		_, err = db.DeleteAPIKeyByIDReturningRow(ctx, key.ID)
+		require.ErrorIs(t, err, sql.ErrNoRows)
+	})
 }
 
 func TestGetAIModelPriceByProviderModel(t *testing.T) {

diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/apikeys.sql b/coderd/database/queries/apikeys.sql
@@ -92,6 +92,15 @@ DELETE FROM
 WHERE
 	id = $1;
 
+-- name: DeleteAPIKeyByIDReturningRow :one
+-- Returns sql.ErrNoRows when the key is already gone, which lets a caller
+-- enforce single use by racing this delete instead of reading first.
+DELETE FROM
+	api_keys
+WHERE
+	id = $1
+RETURNING *;
+
 -- name: DeleteApplicationConnectAPIKeysByUserID :exec
 DELETE FROM
 	api_keys

diff --git a/coderd/oauth2provider/tokens.go b/coderd/oauth2provider/tokens.go
@@ -674,7 +674,12 @@ func refreshTokenGrant(ctx context.Context, db database.Store, logger slog.Logge
 
 	err = db.InTx(func(tx database.Store) error {
 		ctx := dbauthz.As(ctx, actor)
-		err = tx.DeleteAPIKeyByID(ctx, prevKey.ID) // This cascades to the token.
+		// The delete decides the race: only the refresh that removes the key may
+		// mint a replacement, and the loser sees the token as already spent.
+		_, err = tx.DeleteAPIKeyByIDReturningRow(ctx, prevKey.ID) // This cascades to the token.
+		if errors.Is(err, sql.ErrNoRows) {
+			return errBadToken
+		}
 		if err != nil {
 			return xerrors.Errorf("delete oauth2 app token: %w", err)
 		}

diff --git a/coderd/oauth2provider/tokens_test.go b/coderd/oauth2provider/tokens_test.go
@@ -295,25 +295,55 @@ func TestOAuth2TokenExchangeSingleUse(t *testing.T) {
 
 	app := seedAppWithSecret(t, db, sql.NullString{String: scopeInCatalog, Valid: true})
 	code, verifier := authorizeCode(ctx, t, client, app.ID.String(), "workspace:ssh")
-	form := tokenExchangeForm(app, code, verifier)
 
-	type exchange struct {
+	requireExactlyOneMinted(ctx, t, client, tokenExchangeForm(app, code, verifier),
+		"a code may mint at most one token")
+}
+
+// A refresh mints a replacement token and deletes the key the presented one
+// hangs off, so the same race as the exchange applies: the deletion has to
+// arbitrate, or both requests mint from one refresh token.
+func TestOAuth2RefreshSingleUse(t *testing.T) {
+	t.Parallel()
+
+	db, pubsub := dbtestutil.NewDB(t)
+	client := coderdtest.New(t, &coderdtest.Options{
+		Database: db,
+		Pubsub:   pubsub,
+	})
+	coderdtest.CreateFirstUser(t, client)
+	ctx := testutil.Context(t, testutil.WaitLong)
+
+	app := seedAppWithSecret(t, db, sql.NullString{String: scopeInCatalog, Valid: true})
+	code, verifier := authorizeCode(ctx, t, client, app.ID.String(), "workspace:ssh")
+	token := exchangeCode(ctx, t, client, app, code, verifier)
+
+	requireExactlyOneMinted(ctx, t, client, refreshForm(app, token.RefreshToken),
+		"a refresh token may mint at most one replacement")
+}
+
+// requireExactlyOneMinted posts form twice concurrently and requires one 200
+// and one `invalid_grant`.
+func requireExactlyOneMinted(ctx context.Context, t *testing.T, client *codersdk.Client, form url.Values, msg string) {
+	t.Helper()
+
+	type attempt struct {
 		status int
 		body   string
 	}
 
 	var barrier sync.WaitGroup
 	barrier.Add(2)
-	redeem := func() exchange {
+	redeem := func() attempt {
 		barrier.Done()
 		barrier.Wait()
 		status, body := postTokenRequest(ctx, t, client, form)
-		return exchange{status: status, body: body}
+		return attempt{status: status, body: body}
 	}
 
-	other := make(chan exchange, 1)
+	other := make(chan attempt, 1)
 	go func() { other <- redeem() }()
-	results := []exchange{redeem(), <-other}
+	results := []attempt{redeem(), <-other}
 
 	var minted, rejected int
 	for _, result := range results {
@@ -327,7 +357,7 @@ func TestOAuth2TokenExchangeSingleUse(t *testing.T) {
 			t.Fatalf("unexpected status %d: %s", result.status, result.body)
 		}
 	}
-	require.Equal(t, 1, minted, "a code may mint at most one token")
+	require.Equal(t, 1, minted, msg)
 	require.Equal(t, 1, rejected)
 }