github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-23 07:18:56 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[PR #4210] [MERGED] feat(api-key): Organization support in API-Keys & Multiple config support #13500

New Issue
Closed
opened 2026-04-13 08:58:37 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-13 08:58:37 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/better-auth/better-auth/pull/4210
Author: @ping-maxwell
Created: 8/24/2025
Status: ✅ Merged
Merged: 2/24/2026
Merged by: @himself65

Base: canary ← Head: feat/api-keys/org-support

📝 Commits (10+)

  • 737d2f0 feat(api-key): Organization support for api-keys
  • 1e3a79a Merge branch 'canary' into feat/api-keys/org-support
  • e1b2068 Merge branch 'canary' into feat/api-keys/org-support
  • 5a2d476 Merge branch 'canary' into feat/api-keys/org-support
  • a378425 Merge branch 'canary' into feat/api-keys/org-support
  • b2ce237 progress!
  • 734c515 chore: lint
  • 3a605fc update: documentation to use sub-pages
  • fc6ab45 Merge branch 'canary' into feat/api-keys/org-support
  • 707e7bd chore: remove unused files

📊 Changes

37 files changed (+4542 additions, -1806 deletions)

View changed files

📝 docs/components/sidebar-content.tsx (+30 -0)
➖ docs/content/docs/plugins/api-key.mdx (+0 -1377)
➕ docs/content/docs/plugins/api-key/advanced.mdx (+753 -0)
➕ docs/content/docs/plugins/api-key/index.mdx (+493 -0)
➕ docs/content/docs/plugins/api-key/meta.json (+4 -0)
➕ docs/content/docs/plugins/api-key/reference.mdx (+591 -0)
➕ packages/api-key/package.json (+80 -0)
📝 packages/api-key/src/adapter.ts (+64 -64)
📝 packages/api-key/src/api-key.test.ts (+795 -15)
📝 packages/api-key/src/client.ts (+0 -0)
📝 packages/api-key/src/error-codes.ts (+12 -0)
📝 packages/api-key/src/index.ts (+150 -91)
➕ packages/api-key/src/org-api-key.test.ts (+618 -0)
➕ packages/api-key/src/org-authorization.ts (+144 -0)
📝 packages/api-key/src/rate-limit.ts (+0 -0)
📝 packages/api-key/src/routes/create-api-key.ts (+112 -58)
📝 packages/api-key/src/routes/delete-all-expired-api-keys.ts (+0 -0)
📝 packages/api-key/src/routes/delete-api-key.ts (+46 -6)
📝 packages/api-key/src/routes/get-api-key.ts (+45 -9)
➕ packages/api-key/src/routes/index.ts (+177 -0)

...and 17 more files

📄 Description

API Key references & multiple configurations support

Closes https://github.com/better-auth/better-auth/issues/2446

This PR introduces functionality to support multiple api-key configurations, as well as the ability to set a given api-key configuration to either reference users or organizations. Also updates the docs to use sub-pages for the api-keys.

Breaking changes

  • api-key plugin moved to it's own package at @better-auth/api-key
  • ApiKey table schema:
    • userId renamed to referenceId
    • new field: configId (defaults value is default)
  • Plugin options changes:

    • permissions.defaultPermissions's cb function's first argument is now referenceId instead of userId:

       export const auth = betterAuth({
      plugins: [
          apiKey({
              permissions: {
-                  defaultPermissions: async (userId, ctx) => {
+                  defaultPermissions: async (referenceId, ctx) => {
  	                  // Fetch user role or other data to determine permissions
  	                  return {
  	                    files: ["read"],
  	                    users: ["read"],
  	                  };
  	                },
  	            }
  	        })
  	    ]
  })
  • Client SDK changes: 
    // Before
const ownerId = apiKey.userId;

// After
const ownerId = apiKey.referenceId;
const ownerType = apiKey.references; // "user" or "organization"
const configId = apiKey.configId;

Upgrade Checklist

  1. Run database migration to add new columns and migrate userId → referenceId
  2. Clear secondary storage or migrate storage keys
  3. Update client code accessing userId → referenceId
  4. Update any direct database queries using userId field
  5. Test existing API key functionality before removing userId column

Summary by cubic

Adds organization-owned API keys and multiple configurations. Endpoints accept an optional configId and auto-resolve the right configuration; the API Key plugin is now a standalone package (@better-auth/api-key) and docs are split into index, advanced, and reference pages with a nested sidebar.

  • New Features

    • Multiple configurations via a plugin array (unique configId). Per-config headers, rate limits, storage mode, hashing, validators, session mocking; references can be "user" or "organization".
    • Endpoints: create accepts optional configId and organizationId (required for org-owned keys); list/get/verify/update/delete accept optional configId and resolve the key’s configuration; list dedupes storage queries when configs share a backend.
    • Organization authorization: enforce org membership and role permissions for create/read/update/delete on org-owned keys (API_KEY_PERMISSIONS). New errors: USER_NOT_MEMBER_OF_ORGANIZATION, INSUFFICIENT_API_KEY_PERMISSIONS, ORGANIZATION_ID_REQUIRED, INVALID_REFERENCE_ID_FROM_API_KEY, NO_DEFAULT_API_KEY_CONFIGURATION_FOUND.
    • Session mocking works only for user-owned keys; org-owned keys are blocked.
    • Storage/schema: added configId and referenceId with indexes; secondary storage keys now by-ref; schema defaults renamed to defaultTimeWindow/defaultRateLimitMax.

  • Migration

    • Replace userId with referenceId in API key data and queries.
    • Update permissions.defaultPermissions to receive (referenceId, ctx) instead of (userId, ctx).
    • Define organization role permissions for api-key actions if using org-owned keys.
    • Stop sending userId when creating keys; provide organizationId for org-owned keys.
    • Add a configId column and ensure a default configuration exists ("default" or omit configId).
    • Clear or migrate secondary storage keys to the new by-ref format.
    • Install and import @better-auth/api-key instead of the previous plugin path.

Written for commit 89eabf3967. Summary will update on new commits.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/better-auth/better-auth/pull/4210 **Author:** [@ping-maxwell](https://github.com/ping-maxwell) **Created:** 8/24/2025 **Status:** ✅ Merged **Merged:** 2/24/2026 **Merged by:** [@himself65](https://github.com/himself65) **Base:** `canary` ← **Head:** `feat/api-keys/org-support` --- ### 📝 Commits (10+) - [`737d2f0`](https://github.com/better-auth/better-auth/commit/737d2f04ae727c7b34fc4f6843632a3f8144d637) feat(api-key): Organization support for api-keys - [`1e3a79a`](https://github.com/better-auth/better-auth/commit/1e3a79af3c2b19b19e9f340caf5bd093cfdcfd94) Merge branch 'canary' into feat/api-keys/org-support - [`e1b2068`](https://github.com/better-auth/better-auth/commit/e1b2068e77d80a12fd7786c2a04e371f9ef310e9) Merge branch 'canary' into feat/api-keys/org-support - [`5a2d476`](https://github.com/better-auth/better-auth/commit/5a2d476b04bf2efbe8c3beab0ad123292e890b6d) Merge branch 'canary' into feat/api-keys/org-support - [`a378425`](https://github.com/better-auth/better-auth/commit/a37842586e1e7a4867709a2aff76c409f65a0152) Merge branch 'canary' into feat/api-keys/org-support - [`b2ce237`](https://github.com/better-auth/better-auth/commit/b2ce237f179020a09ca65312b8fab87e93730623) progress! - [`734c515`](https://github.com/better-auth/better-auth/commit/734c515cc93028b46a42bcc5933187d27db91b25) chore: lint - [`3a605fc`](https://github.com/better-auth/better-auth/commit/3a605fcfc6308df38fca24e4c1498da8f884611b) update: documentation to use sub-pages - [`fc6ab45`](https://github.com/better-auth/better-auth/commit/fc6ab455bb6e475caaad4337e8c3b9fa43318ac7) Merge branch 'canary' into feat/api-keys/org-support - [`707e7bd`](https://github.com/better-auth/better-auth/commit/707e7bdcc29151f94797f0b3ba96b11c1cb2f67e) chore: remove unused files ### 📊 Changes **37 files changed** (+4542 additions, -1806 deletions) <details> <summary>View changed files</summary> 📝 `docs/components/sidebar-content.tsx` (+30 -0) ➖ `docs/content/docs/plugins/api-key.mdx` (+0 -1377) ➕ `docs/content/docs/plugins/api-key/advanced.mdx` (+753 -0) ➕ `docs/content/docs/plugins/api-key/index.mdx` (+493 -0) ➕ `docs/content/docs/plugins/api-key/meta.json` (+4 -0) ➕ `docs/content/docs/plugins/api-key/reference.mdx` (+591 -0) ➕ `packages/api-key/package.json` (+80 -0) 📝 `packages/api-key/src/adapter.ts` (+64 -64) 📝 `packages/api-key/src/api-key.test.ts` (+795 -15) 📝 `packages/api-key/src/client.ts` (+0 -0) 📝 `packages/api-key/src/error-codes.ts` (+12 -0) 📝 `packages/api-key/src/index.ts` (+150 -91) ➕ `packages/api-key/src/org-api-key.test.ts` (+618 -0) ➕ `packages/api-key/src/org-authorization.ts` (+144 -0) 📝 `packages/api-key/src/rate-limit.ts` (+0 -0) 📝 `packages/api-key/src/routes/create-api-key.ts` (+112 -58) 📝 `packages/api-key/src/routes/delete-all-expired-api-keys.ts` (+0 -0) 📝 `packages/api-key/src/routes/delete-api-key.ts` (+46 -6) 📝 `packages/api-key/src/routes/get-api-key.ts` (+45 -9) ➕ `packages/api-key/src/routes/index.ts` (+177 -0) _...and 17 more files_ </details> ### 📄 Description ## API Key references & multiple configurations support Closes https://github.com/better-auth/better-auth/issues/2446 This PR introduces functionality to support multiple api-key configurations, as well as the ability to set a given api-key configuration to either reference users or organizations. Also updates the docs to use sub-pages for the api-keys. ### Breaking changes * api-key plugin moved to it's own package at `@better-auth/api-key` * ApiKey table schema: * `userId` renamed to `referenceId` * new field: `configId` (defaults value is `default`) * Plugin options changes: * `permissions.defaultPermissions`'s cb function's first argument is now `referenceId` instead of `userId`: ```diff export const auth = betterAuth({ plugins: [ apiKey({ permissions: { - defaultPermissions: async (userId, ctx) => { + defaultPermissions: async (referenceId, ctx) => { // Fetch user role or other data to determine permissions return { files: ["read"], users: ["read"], }; }, } }) ] }) ``` * Client SDK changes: ```ts // Before const ownerId = apiKey.userId; // After const ownerId = apiKey.referenceId; const ownerType = apiKey.references; // "user" or "organization" const configId = apiKey.configId; ``` ## Upgrade Checklist 1. Run database migration to add new columns and migrate userId → referenceId 2. Clear secondary storage or migrate storage keys 3. Update client code accessing userId → referenceId 4. Update any direct database queries using userId field 5. Test existing API key functionality before removing userId column <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Adds organization-owned API keys and multiple configurations. Endpoints accept an optional configId and auto-resolve the right configuration; the API Key plugin is now a standalone package (@better-auth/api-key) and docs are split into index, advanced, and reference pages with a nested sidebar. - New Features - Multiple configurations via a plugin array (unique configId). Per-config headers, rate limits, storage mode, hashing, validators, session mocking; references can be "user" or "organization". - Endpoints: create accepts optional configId and organizationId (required for org-owned keys); list/get/verify/update/delete accept optional configId and resolve the key’s configuration; list dedupes storage queries when configs share a backend. - Organization authorization: enforce org membership and role permissions for create/read/update/delete on org-owned keys (API_KEY_PERMISSIONS). New errors: USER_NOT_MEMBER_OF_ORGANIZATION, INSUFFICIENT_API_KEY_PERMISSIONS, ORGANIZATION_ID_REQUIRED, INVALID_REFERENCE_ID_FROM_API_KEY, NO_DEFAULT_API_KEY_CONFIGURATION_FOUND. - Session mocking works only for user-owned keys; org-owned keys are blocked. - Storage/schema: added configId and referenceId with indexes; secondary storage keys now by-ref; schema defaults renamed to defaultTimeWindow/defaultRateLimitMax. - Migration - Replace userId with referenceId in API key data and queries. - Update permissions.defaultPermissions to receive (referenceId, ctx) instead of (userId, ctx). - Define organization role permissions for api-key actions if using org-owned keys. - Stop sending userId when creating keys; provide organizationId for org-owned keys. - Add a configId column and ensure a default configuration exists ("default" or omit configId). - Clear or migrate secondary storage keys to the new by-ref format. - Install and import @better-auth/api-key instead of the previous plugin path. <sup>Written for commit 89eabf3967f221b8f900829a66f74a241833d005. Summary will update on new commits.</sup> <!-- End of auto-generated description by cubic. --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-13 08:58:37 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#13500
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?