Environments

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
    }]
  }'

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_live",
    "meta": {
      "environment": "production"
    },
    "ratelimits": [{
      "name": "requests",
      "limit": 1000,
      "duration": 60000
    }]
  }'

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/min
const 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 data
try {
  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

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

When to use this

Safe development

Automated testing

Different limits

Prevent accidents

How it works

Create environment-specific keys

Verify and check environment

Handle environments in your API

Common patterns

Different rate limits per environment

Sandbox vs real resources

Block test keys from production endpoint

Next steps

API Keys overview

Rate limiting

​When to use this

Safe development

Automated testing

Different limits

Prevent accidents

​How it works

​Create environment-specific keys

​Verify and check environment

​Handle environments in your API

​Common patterns

​Different rate limits per environment

​Sandbox vs real resources

​Block test keys from production endpoint

​Next steps

API Keys overview

Rate limiting

When to use this

How it works

Create environment-specific keys

Verify and check environment

Handle environments in your API

Common patterns

Different rate limits per environment

Sandbox vs real resources

Block test keys from production endpoint

Next steps