Unkey v2 represents a major infrastructure upgrade with enhanced caching and cache invalidation systems. While the core functionality remains the same, there are important changes to request and response structures that require updates to your integration.
The v2 API is available at api.unkey.com (instead of api.unkey.dev). The v1 API is deprecated and will be shut down at the end of the year 2025.

​
Quick Start

The fastest way to migrate is to update your SDK: 
npm install @unkey/api@latest
The v2 SDK automatically points to the new endpoint and guides you through all request/response changes via its types.

​
Why Migrate to v2?

​
Proven Performance Improvements

Our v2 changes produce measurable latency improvements across all regions:

Global P95 Latency improvement for key verifications when switching from v1 to v2

​
Key Changes of v2

  • New Domain: API available at api.unkey.com instead of api.unkey.dev
  • Enhanced Caching: Server-based infrastructure with improved caching mechanisms
  • Improved Invalidations: Enhanced cache invalidation system across regions
  • Improved Developer Experience: More consistent error handling and response formats

​
What You Need to Change

The main changes you’ll need to make when migrating:
  • Update your base URL from api.unkey.dev to api.unkey.com (The SDKs do this automatically starting at v2.0.0)
  • Change response parsing from direct responses to response.data
  • Handle new error format with hierarchical error codes and request IDs

​
Response Format Changes

All v2 responses now use a standardized envelope format with meta and data fields:

​
v1 Response Format

{
  "valid": true,
  "keyId": "key_123",
  "name": "Production API Key"
}

​
v2 Response Format

{
  "meta": {
    "requestId": "req_abc123"
  },
  "data": {
    "valid": true,
    "keyId": "key_123",
    "name": "Production API Key"
  }
}

​
Detailed Migration by Category

Choose the endpoint category you need to migrate:

Keys Endpoints

Key creation, verification, updates, permissions, and roles

APIs Endpoints

API namespace creation, retrieval, and key listing

Identities Endpoints

Identity management and shared rate limits

Permissions Endpoints

Standalone permission and role management

Rate Limiting Endpoints

Rate limiting and override management

Error Handling

Error response format changes and codes

​
Getting Help