API Key Management#

Dokploy's API key system is built on the better-auth library's @better-auth/api-key plugin. Keys are scoped to a user + organization pair — the referenceId on the apikey table points to the owning user 1, and the organization ID is stored as a JSON string in the metadata column 2. Every authenticated tRPC call can use either a session cookie or an x-api-key header.

Plugin Registration#

The apiKey plugin is registered in packages/server/src/lib/auth.ts with enableMetadata: true and references: "user". The resulting auth export exposes createApiKey and the internal verifyApiKey callable 3.

Database Schema#

The apikey table is defined in packages/server/src/db/schema/account.ts. Key columns:

Zod Validation Schema (tRPC)#

The input schema apiCreateApiKey is defined at the top of apps/dokploy/server/api/routers/user.ts:

• name — required, min length 1
• prefix — optional string
• expiresIn — optional number (seconds)
• metadata.organizationId — required string; used to scope the key to an org
• rateLimitEnabled, rateLimitTimeWindow, rateLimitMax — optional rate-limit config
• remaining, refillAmount, refillInterval — optional request-count limiting

tRPC Procedures#

Both procedures live in userRouter in apps/dokploy/server/api/routers/user.ts:

user.createApiKey 12 — protectedProcedure:

1. Verifies the caller is a member of metadata.organizationId.
2. Calls the createApiKey service function which delegates to auth.createApiKey(...) and then writes the metadata JSON back to the DB.
3. Emits an audit log entry.

user.deleteApiKey 13 — protectedProcedure:

1. Looks up the key by ID.
2. Guards that referenceId === ctx.user.id (only the key owner can delete it).
3. Hard-deletes the row and emits an audit log entry.

The user.get query also returns a user's keys with id, name, prefix, enabled, expiresAt, and createdAt columns 14 — this is the data source for the profile/settings UI.

Request-Time Validation (validateRequest)#

The validateRequest function in auth.ts handles both auth methods:

1. API key path — If an x-api-key header is present, it calls api.verifyApiKey({ body: { key } }) 15.
2. Org resolution — After a valid key, it reads metadata.organizationId from the DB record and looks up the matching member row to build a mock session with role, ownerId, and enableEnterpriseFeatures set correctly 16.
3. Session cookie path — Falls back to api.getSession(...) for cookie-based auth 17.

Invalid or missing organizationId in metadata short-circuits to { session: null, user: null } 18.

Key Entry Points#