Temporary Keys - Unkey Docs

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 hoursEXPIRES=$(($(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'  }'

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 nowEXPIRES=$(($(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'  }'

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 limitingtry {  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."

Next steps#

Usage limits

Cap total requests per key

Key rotation

Generate new keys while maintaining config