[GH-ISSUE #3640] Bug: remaining defaults to refillAmount when null in create-api-key.ts #26992

New Issue

GiteaMirror · 2026-04-17T17:46:02-05:00

GiteaMirror commented

2026-04-17 17:46:02 -05:00

Originally created by @eaoliver on GitHub (Jul 27, 2025).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/3640

Is this suited for github?

Yes, this is suited for github

To Reproduce

There is a bug in packages/better-auth/src/plugins/api-key/routes/create-api-key.ts

In the code, the following line assigns remaining: remaining: remaining || refillAmount || null,

So setting the remaining as null to remove the cap on API usage causes it to set remaining to the refillAmount value. This creates a key usage cap when there shouldn't be.

To reproduce, create an ApiKey with the remaining set to null as follows:

const apiKeyData = await auth.api.createApiKey({
          body: {
            name: SYSTEM_TITLE_ABRV,
            expiresIn: null, // seconds or never
            userId: newUser.user.id,
            prefix: API_KEY_PREFIX,
            metadata: metadata,
            // permissions,

            // Enable rate limit throttling
            rateLimitEnabled: true,
            rateLimitTimeWindow: RATE_LIMIT_TIME_WINDOW,
            rateLimitMax: RATE_LIMIT_MAX,
            remaining: null, // There is no cap on usage.
            // Refill the API key one request per second
            refillAmount: 1,
            refillInterval: 1000,
          },
        });

This will cause remaining to be set from null to 1.

Current vs. Expected behavior

Setting remaining to null should keep it null.

What version of Better Auth are you using?

1.3.3

Provide environment information

Node 20

Which area(s) are affected? (Select all that apply)

Backend

Auth config (if applicable)

Not relevant.

Additional context

Tested on the latest version of better-auth.
The bug is on line 422 of https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/plugins/api-key/routes/create-api-key.ts

Originally created by @eaoliver on GitHub (Jul 27, 2025). Original GitHub issue: https://github.com/better-auth/better-auth/issues/3640 ### Is this suited for github? - [x] Yes, this is suited for github ### To Reproduce There is a bug in packages/better-auth/src/plugins/api-key/routes/create-api-key.ts In the code, the following line assigns remaining: `remaining: remaining || refillAmount || null,` So setting the `remaining` as null to remove the cap on API usage causes it to set remaining to the refillAmount value. This creates a key usage cap when there shouldn't be. To reproduce, create an ApiKey with the `remaining` set to null as follows: ``` const apiKeyData = await auth.api.createApiKey({ body: { name: SYSTEM_TITLE_ABRV, expiresIn: null, // seconds or never userId: newUser.user.id, prefix: API_KEY_PREFIX, metadata: metadata, // permissions, // Enable rate limit throttling rateLimitEnabled: true, rateLimitTimeWindow: RATE_LIMIT_TIME_WINDOW, rateLimitMax: RATE_LIMIT_MAX, remaining: null, // There is no cap on usage. // Refill the API key one request per second refillAmount: 1, refillInterval: 1000, }, }); ``` This will cause `remaining` to be set from null to 1. ### Current vs. Expected behavior Setting `remaining` to null should keep it null. ### What version of Better Auth are you using? 1.3.3 ### Provide environment information ```bash Node 20 ``` ### Which area(s) are affected? (Select all that apply) Backend ### Auth config (if applicable) ```typescript Not relevant. ``` ### Additional context Tested on the latest version of better-auth. The bug is on line 422 of https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/plugins/api-key/routes/create-api-key.ts

GiteaMirror added the locked bug labels 2026-04-17 17:46:02 -05:00

GiteaMirror closed this issue

2026-04-17 17:46:03 -05:00

GiteaMirror commented

2026-04-17 17:46:04 -05:00

@dosubot[bot] commented on GitHub (Jul 27, 2025):

You're right—this is a bug. The line remaining: remaining || refillAmount || null uses the logical OR operator, so if you set remaining to null, it falls through and assigns refillAmount instead. This means you can't explicitly set remaining to null to indicate "no cap"—it always gets a value if refillAmount is present, which is not the intended behavior. The schema and downstream logic treat remaining: null as "unlimited" usage, so this assignment is incorrect [source].

To fix this, change the assignment to use the nullish coalescing operator (??), which only falls back if remaining is null or undefined:

remaining: remaining ?? refillAmount ?? null,

This way, if you explicitly set remaining: null, it will stay null and not default to refillAmount.

As a workaround until this is fixed, you could avoid passing refillAmount when you want unlimited usage, but the real solution is to update the code as above.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Jul 27, 2025):  You're right—this is a bug. The line `remaining: remaining || refillAmount || null` uses the logical OR operator, so if you set `remaining` to `null`, it falls through and assigns `refillAmount` instead. This means you can't explicitly set `remaining` to `null` to indicate "no cap"—it always gets a value if `refillAmount` is present, which is not the intended behavior. The schema and downstream logic treat `remaining: null` as "unlimited" usage, so this assignment is incorrect [[source]](https://github.com/better-auth/better-auth/blob/e7af3aa80c0cce284ed7ef3b61056322e50cd964/packages/better-auth/src/plugins/api-key/routes/create-api-key.ts). To fix this, change the assignment to use the nullish coalescing operator (`??`), which only falls back if `remaining` is `null` or `undefined`: ```ts remaining: remaining ?? refillAmount ?? null, ``` This way, if you explicitly set `remaining: null`, it will stay `null` and not default to `refillAmount`. As a workaround until this is fixed, you could avoid passing `refillAmount` when you want unlimited usage, but the real solution is to update the code as above.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- How did I do? [Good](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/dba8a316-2c8f-43c3-8f56-a86c2ff3888b?feedback_type=other)  [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github) [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/3640)

GiteaMirror commented

2026-04-17 17:46:05 -05:00

@eaoliver commented on GitHub (Jul 27, 2025):

This way, if you explicitly set remaining: null, it will stay null and not default to refillAmount.

@dosu you are incorrect again. That is not how the ?? operator works.

@eaoliver commented on GitHub (Jul 27, 2025): > This way, if you explicitly set remaining: null, it will stay null and not default to refillAmount. @dosu you are incorrect again. That is not how the ?? operator works.

GiteaMirror commented

2026-04-17 17:46:05 -05:00

@dosubot[bot] commented on GitHub (Jul 27, 2025):

You're right—the nullish coalescing operator (??) does not preserve an explicit null. If you use remaining: remaining ?? refillAmount ?? null, and remaining is set to null, it will still fall through and assign refillAmount—not what you want for an "unlimited" cap. The same problem exists with the logical OR (||), which also treats null (and other falsy values like 0) as a signal to fall through.

To preserve an explicit null, you need to check for it directly. For example:

remaining: remaining === null ? null : (remaining !== undefined ? remaining : (refillAmount ?? null)),

This way, if you set remaining to null, it stays null and doesn't default to refillAmount. This matches the schema and intended behavior for unlimited usage keys in the codebase (source). This pattern is important for other nullable fields as well.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Jul 27, 2025):  You're right—the nullish coalescing operator (??) does not preserve an explicit null. If you use `remaining: remaining ?? refillAmount ?? null`, and `remaining` is set to `null`, it will still fall through and assign `refillAmount`—not what you want for an "unlimited" cap. The same problem exists with the logical OR (`||`), which also treats `null` (and other falsy values like 0) as a signal to fall through. To preserve an explicit `null`, you need to check for it directly. For example: ```ts remaining: remaining === null ? null : (remaining !== undefined ? remaining : (refillAmount ?? null)), ``` This way, if you set `remaining` to `null`, it stays `null` and doesn't default to `refillAmount`. This matches the schema and intended behavior for unlimited usage keys in the codebase ([source](https://github.com/better-auth/better-auth/blob/e7af3aa80c0cce284ed7ef3b61056322e50cd964/packages/better-auth/src/plugins/api-key/types.ts)). This pattern is important for other nullable fields as well.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- How did I do? [Good](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/ce2e1cf7-6ce4-47f3-b6ce-88b1d880b15a?feedback_type=other)  [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github) [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/3640)

GiteaMirror commented

2026-04-17 17:46:06 -05:00

@eaoliver commented on GitHub (Jul 27, 2025):

or better still @dosu :

remaining: remaining === null ? remaining : (remaining ?? refillAmount ?? null),

@eaoliver commented on GitHub (Jul 27, 2025): or better still @dosu : ` remaining: remaining === null ? remaining : (remaining ?? refillAmount ?? null),`

GiteaMirror commented

2026-04-17 17:46:06 -05:00

@dosubot[bot] commented on GitHub (Jul 27, 2025):

Yes, your proposed code—remaining: remaining === null ? remaining : (remaining ?? refillAmount ?? null),—is correct for this use case. It explicitly preserves remaining: null (for unlimited usage), while still allowing fallback to refillAmount or null only if remaining is undefined. This matches the schema and intended behavior in the codebase, where remaining: null means "no cap" and any number means "capped" [source]. This approach avoids the pitfalls of both || and ??, which would otherwise override an explicit null.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Jul 27, 2025):  Yes, your proposed code—`remaining: remaining === null ? remaining : (remaining ?? refillAmount ?? null),`—is correct for this use case. It explicitly preserves `remaining: null` (for unlimited usage), while still allowing fallback to `refillAmount` or `null` only if `remaining` is `undefined`. This matches the schema and intended behavior in the codebase, where `remaining: null` means "no cap" and any number means "capped" [[source]](https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/plugins/api-key/routes/create-api-key.ts). This approach avoids the pitfalls of both `||` and `??`, which would otherwise override an explicit `null`.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- How did I do? [Good](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/399c44c3-0b8b-452c-8f24-2b4a059b0bef?feedback_type=other)  [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github) [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/3640)

GiteaMirror commented

2026-04-17 17:46:07 -05:00

@ping-maxwell commented on GitHub (Jul 28, 2025):

Setting remaining to null means it has infinite use. However in your case you're also adding a refillInterval and refillAmount, why need that if it's already infinite use?

@ping-maxwell commented on GitHub (Jul 28, 2025): Setting `remaining` to null means it has infinite use. However in your case you're also adding a refillInterval and refillAmount, why need that if it's already infinite use?

GiteaMirror commented

2026-04-17 17:46:08 -05:00

@eaoliver commented on GitHub (Jul 28, 2025):

My presumption is that refillAmount is the rate in which a token bucket is replenished. This is related to the other bug I posted: #3573.

There seem to be two approaches to rate limiting in better-auth: a finite number of tokens replenished per refillInterval and refillAmount on a daily? basis (like a daily quota), and a maxRequests bucket that is consumed and replenished after rateLimitTimeWindow of inactivity.

In the second case, it would be ideal if the rate limiting on API key verification was a token bucket that replenished at a certain refill rate up to a maximum bucket size.

@eaoliver commented on GitHub (Jul 28, 2025): My presumption is that `refillAmount` is the rate in which a token bucket is replenished. This is related to the other bug I posted: #3573. There seem to be two approaches to rate limiting in better-auth: a finite number of tokens replenished per `refillInterval` and `refillAmount` on a _daily?_ basis (like a daily quota), and a `maxRequests` bucket that is consumed and replenished after `rateLimitTimeWindow ` of inactivity. In the second case, it would be ideal if the rate limiting on API key verification was a token bucket that replenished at a certain refill rate up to a maximum bucket size.

Sign in to join this conversation.

Branches Tags

dependabot/npm_and_yarn/demo/electron/demo-minor-patch-227a091249

dependabot/github_actions/github-actions-98f3470200

2026-05-13/ci/stabilize-docker-startup

dependabot/npm_and_yarn/samlify-2.13.0

changeset-release/main

main

2026-05-22/chore/adopt-agents-md

2026-05-22/refactor/string-case-utils

2026-05-14/fix/passkey-verify-error-and-claim

changeset-release/next

client-assertions-main

2026-05-15/ci/fix-sqlite-abi-mismatch

2026-05-15/fix/organization-team-add-cascade

2026-05-15/fix/parse-set-cookie-value-validation

2026-05-13/feat/captcha-wildcard-endpoints

fix/i18n-before-hook-translation

fix/disable-migration-generate

2026-05-07/fix/admin-set-password-upsert

2026-05-10/fix/cookie-drain-order

2026-05-10/feat/hooks-finally

2026-05-09/fix/cookie-drain-order

2026-05-09/feat/hooks-finally

2026-05-08/feat/register-before-send

fix/stripe/subscription-data-merge

2026-05-01/chore/pnpm-v11-harden

chore/pnpm-v11

2026-04-29/feat/google-include-granted-scopes

2026-04-29/fix/oauth-account-scope-semantics

2026-04-27/fix/nextcookies-idempotent-writes

2026-04-26/fix/harden-proxy-host-validation

2026-04-26/refactor/stripe-callback-signature-cleanup

2026-04-26/fix/stripe-subscription-callback-timing

2026-04-11/fix/sveltekit-app-modules

feat/open-api-zod-contract

feat/oauth-provider-backchannel-logout-next

feat/oauth-idp-initiated-bounce

refactor/sign-in-challenges

2026-04-21/fix/oauth-rfc-input-validation

fix/release-notes-new-packages

fix/two-factor-identity-guard

fix/resource

feat/emailpassword-authorize

2026-04-12/security/dynamic-baseurl-proxy-trust-default

feat/oauth-provider-at-hash-v2

fix/release-grep-fallback

claude/address-review-comments-JhFLr

claude/slack-update-stripe-docs-consistency-8Sc0w

feat/async-auth

fix/two-factor-totp-verified-enrollment

feat/plugin-ui

codex/blog-1-6-release-post

2026-04-06/fix/type-any-guards

2026-04-05/chore/downgrade-better-call

2026-04-04/ci/skip-vercel-fork-prs

2026-03-28/ci/add-autofix-ci

chore/release-preview-script

himself65/2026/02/19/role

2026-03-24/fix/update-user-info-on-link

2026-03-20/docs/improve-website

2026-03-20/fix/anonymous-onlinkaccount-expo

2026-02-17/fix/anonymous-link-state

fix/8607-saml-inresponseto

fix/8549-scim-patch-noop

v1.4.x

refactor/migration-snapshot-tests

worktree-magic-link-additional-data

chore/migrate-build-to-rollup

worktree-fix-dynamic-baseurl-8447

2026-03-06/chore/public-api-check

fix/close-8156-regression-test

fix/secondary-storage-json-error-handling

himself65/verification-namespace

cursor/issue-8307-validation-79a3

himself65/2026/01/30/error-mdx

v1.4.x-staging

fix/email-otp-user

fix/restrict-full-organization-access-roles

himself65/2026/02/12/count

himself65/2026/02/04/define-plugin

2026-02-04/feat/add-pluralize

cursor/better-auth-js-integration-ec21

cursor/expo-state-mismatch-394c

2026-02-01/fix/org-update-role-sync-members

cursor/issue-7607-investigation-e146

cursor/email-generation-helper-0ff6

himself65/2026/01/21/avoid-spread-operator

himself65/2026/01/14/cli

claude/slack-add-docs-pr-NMvgO

claude/slack-add-advanced-useplural-WHKYL

feat/hooks-pos

feat/2fa-phone

feat/2fa

fix/rotation

fix/username-check

v1.3.x

refactor/organization

feat/multiple-client-ids-social-providers

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/better-auth#26992