Security

Endpoint proxy pattern

API keys are kept exclusively on the server. UploadKitProvider accepts an endpoint prop that points to a Next.js Route Handler (e.g. /api/uploadkit). Browser components call this local endpoint — your server holds UPLOADKIT_API_KEY and proxies the request to the UploadKit API. The key never touches the browser.

Browser → /api/uploadkit (your server, holds UPLOADKIT_API_KEY) → api.uploadkit.dev

// The endpoint prop points to your server route — no key in the browser
<UploadKitProvider endpoint="/api/uploadkit">
  {children}
</UploadKitProvider>

// WRONG — do not pass the API key directly to the provider.
// The key would be bundled into the browser and visible to any user.
// Use endpoint="/api/uploadkit" instead (see correct example above).

The route handler created by createUploadKitHandler is where the API key lives:

import { createUploadKitHandler } from '@uploadkitdev/next';

export const { GET, POST } = createUploadKitHandler({
  router: fileRouter,
  apiKey: process.env.UPLOADKIT_API_KEY, // server env only — never NEXT_PUBLIC_
});

API key authentication

Every request to the UploadKit API must include a valid API key in the x-api-key header. UploadKit issues two types of keys:

How keys are stored:

API keys are hashed with SHA-256 before being stored in the database. Only the SHA-256 hash of the key is persisted — UploadKit cannot recover or display a key after creation. If you lose a key, delete it and create a new one.

The key prefix (uk_live_ + first few characters) is stored alongside the hash for display in the dashboard — you can identify which key is which without exposing the full key value.

File validation

File type and size are validated twice: once when the presigned URL is issued, and again when the upload is confirmed.

At presign time (server-side)

When a client requests a presigned URL, UploadKit's API checks:

1. File type — Is contentType in the route's allowedTypes list? Wildcards like image/* are expanded against the provided MIME type.
2. File size — Is fileSize ≤ min(route.maxFileSize, tier.maxFileSizeBytes)? The more restrictive of your route configuration and your subscription tier applies.
3. Route exists — Does the routeSlug match a configured route for this project?
4. Middleware — Did your route's middleware() function return without throwing?

At completion time (server-side)

After the client PUTs the file and calls /upload/complete, UploadKit verifies the upload:

1. R2/S3 HEAD request — Confirms the file actually exists in storage
2. ContentType match — The stored object's content type must match the presign declaration
3. Size match — The actual object size must match fileSize from the presign request

If either check fails, the file is marked failed and not counted against your quota.

Presigned URL security

Presigned URLs include the following parameters locked into the cryptographic signature:

The Content-Type and Content-Length locking is enforced at the storage layer (R2/S3), not by UploadKit's servers. Even if UploadKit's API were bypassed, the storage provider would reject requests with mismatched parameters.

Rate limiting

UploadKit uses a sliding window rate limiter backed by Upstash Redis. Limits are applied per API key:

Rate limit headers are returned on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1712488920

When the limit is exceeded, UploadKit returns 429 Too Many Requests. The client SDK automatically retries with exponential backoff up to maxRetries attempts.

Tier limits

In addition to per-request rate limits, each subscription tier enforces cumulative storage and bandwidth limits per billing period:

Exceeding a storage or bandwidth limit on the Free plan blocks further uploads until the next billing period. On Pro and above, usage is metered and billed as overage — uploads continue uninterrupted.

BYOS credential safety

When using Bring Your Own Storage, your S3/R2 credentials live in server-side environment variables and are never exposed to the browser:

Server environment                          Browser
─────────────────────                       ──────────────────────
AWS_ACCESS_KEY_ID    ─┐                     No credentials visible
AWS_SECRET_ACCESS_KEY ┤→ Generate presigned URL → send URL to browser
R2_BUCKET_NAME       ─┘                     (URL is time-limited, single-object scoped)

The storage config in createUploadKitHandler is processed at request time on your server. It is bundled with your server code, not your client bundle — Next.js App Router ensures server-only code never reaches the browser.

Best practices

API key security:

• Use uk_test_ keys in development and CI — they never create real storage or charges
• Create one key per service (e.g. separate keys for your Next.js app and your data pipeline)
• Store keys in environment variables, not source code
• Rotate keys quarterly or immediately after any potential exposure

Environment variables:

• UPLOADKIT_API_KEY — server-side only; never prefix with NEXT_PUBLIC_
• UploadKitProvider uses an endpoint prop pointing to your server route — no client-side key variable needed

BYOS credentials:

• All storage credentials are server-side only
• Follow the principle of least privilege: grant only s3:PutObject, s3:GetObject, s3:DeleteObject, and s3:AbortMultipartUpload — nothing more
• Use separate IAM users or service accounts per environment

Middleware:

• Always authenticate requests in middleware() — throw on unauthorized
• Never trust client-supplied metadata for authorization decisions
• Return only the data you need in middleware — it flows to onUploadComplete and is logged

File validation:

• Rely on allowedTypes for server-side MIME enforcement — don't do client-side-only validation
• Set maxFileSize explicitly on every route — the default is your tier's maximum