Temporary Keys

Temporary keys automatically become invalid after a specified time. No cleanup required, Unkey handles expiration and deletion for you.

When to use this

Trial access

Give new users a 7-day trial key. It stops working automatically.

Time-limited integrations

Partner needs API access for a project? Key expires when the project ends.

Session-based access

Generate a key that lasts for a user’s session (e.g., 24 hours).

Security rotations

Force key rotation by having keys expire periodically.

How it works

Create a key with an expires timestamp (Unix milliseconds)
Key works normally until the expiration time
After expiration, verification returns code: EXPIRED
Unkey automatically cleans up expired keys

Create a temporary key

Set expires to a Unix timestamp in milliseconds:

# Key expires in 24 hours
EXPIRES=$(($(date +%s) * 1000 + 86400000))

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "expires": '$EXPIRES'
  }'

// Key expires in 24 hours
const expires = Date.now() + 24 * 60 * 60 * 1000;

try {
  const { meta, data } = await unkey.keys.createKey({
    apiId: "api_...",
    expires,
  });
} catch (err) {
  console.error(err);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

import time

# Key expires in 24 hours
expires = int(time.time() * 1000) + (24 * 60 * 60 * 1000)

result = unkey.keys.create_key(
    api_id="api_...",
    expires=expires
)

Common expiration times

Duration	Calculation
1 hour	`Date.now() + 60 * 60 * 1000`
24 hours	`Date.now() + 24 * 60 * 60 * 1000`
7 days	`Date.now() + 7 * 24 * 60 * 60 * 1000`
30 days	`Date.now() + 30 * 24 * 60 * 60 * 1000`
Specific date	`new Date("2024-12-31").getTime()`

Verification response

When verifying an expired key:

{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": false,
    "code": "EXPIRED",
    "keyId": "key_..."
  }
}

Extend or change expiration

Update the expiration time on an existing key:

# Extend by 7 more days from now
EXPIRES=$(($(date +%s) * 1000 + 604800000))

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "expires": '$EXPIRES'
  }'

// Extend by 7 more days from now
try {
  const { meta, data } = await unkey.keys.updateKey({
    keyId: "key_...",
    expires: Date.now() + 7 * 24 * 60 * 60 * 1000,
  });
} catch (err) {
  console.error(err);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

Remove expiration

Make a temporary key permanent by setting expires to null:

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "expires": null
  }'

Combining with other features

Temporary keys work with all other key features:

// 7-day trial with 1000 requests and rate limiting
try {
  const { meta, data } = await unkey.keys.createKey({
    apiId: "api_...",
    expires: Date.now() + 7 * 24 * 60 * 60 * 1000,
    credits: {
      remaining: 1000,
    },
    ratelimits: [
      {
        name: "requests",
        limit: 100,
        duration: 60000, // 100 per minute
      },
    ],
  });
} catch (err) {
  console.error(err);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

Temporary vs usage-limited keys

Feature	Temporary Keys	Usage-Limited Keys
Controlled by	Time	Request count
Expires when	Clock hits timestamp	Credits reach 0
Good for	Time-bound access	Pay-per-use, quotas
Example	”Access for 7 days"	"1000 requests total”

Use both together for trial limits: “7 days OR 1000 requests, whichever comes first.”

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

When to use this

Trial access

Time-limited integrations

Session-based access

Security rotations

How it works

Create a temporary key

Common expiration times

Verification response

Extend or change expiration

Remove expiration

Combining with other features

Temporary vs usage-limited keys

Next steps

Usage limits

Key rotation

​When to use this

Trial access

Time-limited integrations

Session-based access

Security rotations

​How it works

​Create a temporary key

​Common expiration times

​Verification response

​Extend or change expiration

​Remove expiration

​Combining with other features

​Temporary vs usage-limited keys

​Next steps

Usage limits

Key rotation

When to use this

How it works

Create a temporary key

Common expiration times

Verification response

Extend or change expiration

Remove expiration

Combining with other features

Temporary vs usage-limited keys

Next steps