Environments - Unkey Docs

Environments let you issue distinct keys for development, staging, and production. Test keys can't affect real resources, while live keys have full access.

When to use this#

Safe development

Developers can test integrations without touching production data.

Automated testing

CI/CD pipelines can run tests with keys that won't affect live resources.

Different limits

Test keys might have lower rate limits or be free to use.

Prevent accidents

Prefixes like sk_test_ make it obvious when using non-production keys.

How it works#

Environments are implemented using key metadata and prefixes, there's no special "environment" field. This gives you full flexibility to model environments however you want.

Common pattern:

Prefix: sk_test_ vs sk_live_ (visible to users)
Metadata: { "environment": "test" } (returned on verification)

Create environment-specific keys#

curl -X POST https://api.unkey.com/v2/keys.createKey \  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \  -H "Content-Type: application/json" \  -d '{    "apiId": "api_...",    "prefix": "sk_test",    "meta": {      "environment": "test"    },    "ratelimits": [{      "name": "requests",      "limit": 100,      "duration": 60000    }]  }'

Tip

Using prefixes makes it obvious to users which environment a key is for. This prevents accidental use of test keys in production (or worse, live keys in tests).

Verify and check environment#

The metadata is returned during verification, so your API can behave differently:

curl -X POST https://api.unkey.com/v2/keys.verifyKey \  -H "Content-Type: application/json" \  -d '{ "key": "sk_test_abc123..." }'

Response:

{  "meta": { "requestId": "req_..." },  "data": {    "valid": true,    "keyId": "key_...",    "meta": {      "environment": "test"    }  }}

Handle environments in your API#

try {  const { data } = await unkey.keys.verifyKey({ key: request.apiKey });  if (!data.valid) {    return unauthorized();  }  const environment = data.meta?.environment ?? "production";  if (environment === "test") {    // Use test database, sandbox resources, etc.    return handleTestRequest(request);  }  // Production request  return handleLiveRequest(request);} catch (err) {  console.error(err);  return Response.json({ error: "Internal error" }, { status: 500 });}

Common patterns#

Different rate limits per environment#

// Test: 100/min, Live: 10,000/minconst ratelimits =  environment === "test"    ? [{ name: "requests", limit: 100, duration: 60000 }]    : [{ name: "requests", limit: 10000, duration: 60000 }];try {  const { meta, data } = await unkey.keys.createKey({    apiId,    prefix: environment === "test" ? "sk_test" : "sk_live",    meta: { environment },    ratelimits,  });} catch (err) {  console.error(err);  return Response.json({ error: "Internal error" }, { status: 500 });}

Sandbox vs real resources#

if (data.meta?.environment === "test") {  // Return mock data or use sandbox  return {    charged: false,    response: mockResponse,  };}// Real billing, real datatry {  await chargeUser(data.identity.externalId, amount);  return { charged: true, response: realResponse };} catch (err) {  console.error(err);  return Response.json({ error: "Internal error" }, { status: 500 });}

Block test keys from production endpoint#

if (data.meta?.environment === "test" && isProductionEndpoint) {  return Response.json(    { error: "Test keys cannot access production endpoints" },    { status: 403 },  );}// Continue with your API logic

Next steps#

API Keys overview

Learn about key metadata and features

Rate limiting

Set different limits per environment