Skip to content

API keys

With apiKeys: true, users create API keys in their profile, so their scripts, cron jobs and other servers can call your backend as them without a browser session. Each key can expire and be revoked on its own. The feature runs on Better Auth’s API key plugin (@better-auth/api-key).

Turn it on

src/convex/auth.constants.ts

The API keys section then appears in <UserProfile />, below the linked accounts.

What users can do

  • Create a key with a name and an expiration: 7, 30, 60 or 90 days, a custom date, or no expiration. The form starts at 30 days.
  • Copy the secret right after creating the key. The dialog says “Copy and store this key now. You won’t be able to see it again.” and it doesn’t.
  • Update a key to rename it or change its expiration.
  • Delete a key. It stops working at once.

Verify keys on your server

The Auth UI creates and manages keys, but it ships no code that checks a key on an incoming request. Write that check where you handle the request: createAuth(ctx) in src/convex/auth.ts returns the Better Auth instance, and the plugin adds verifyApiKey to its api. Better Auth’s API key plugin docs describe its arguments, its result and the key’s permissions and rate limits.

Keys and deleted users

When a user deletes their account, or an admin deletes it, their API keys are deleted too, through the user onDelete trigger in src/convex/auth.ts. This happens even while apiKeys is off.

Turning apiKeys off hides the section and removes the plugin, but keeps the keys. They verify again once you turn it back on, so delete keys you no longer trust before you do.