keys.updateKey to change what a key can do without issuing a new one. The key string stays the same, so your users keep working. Only keyId is required.
For every other field:
- Leave it out to keep the current value.
- Send a value to replace it.
- Send
nullto clear it, for example to remove an expiry, a refill schedule, or an identity link.
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys, and pass it as
Authorization: Bearer <root key>. See Permission reference for every permission.api.*.update_key or api.<api_id>.update_key. Without it you get HTTP 403 err:unkey:authorization:insufficient_permissions. A keyId that doesn’t exist or belongs to another workspace returns HTTP 404 err:unkey:data:key_not_found. See Root key permissions.
Request fields
string
required
The key’s ID (
key_...), not the key string. 3 to 255 characters matching ^[a-zA-Z0-9_]+$.string | null
1 to 255 characters.
null removes the name.string | null
1 to 255 characters matching
^[a-zA-Z0-9_.-]+$. Moves the key to the identity with that externalId, creating the identity in the keyspace’s project if it doesn’t exist yet. An existing identity in a different project is rejected with HTTP 404 err:unkey:data:identity_not_found. null unlinks the key from its identity. See Identities.object | null
JSON with at most 100 top-level properties. It replaces the old metadata rather than merging.
null removes it. See Metadata and tags.integer | null
Unix timestamp in milliseconds, at most
4102444800000 (1 January 2100). null makes the key permanent. A timestamp in the past is accepted and expires the key at once. See Key expiration.object | null
credits.remaining (integer or null, 0 or more) and credits.refill (object or null). Unlike keys.createKey, neither is required, so you can change a schedule without resending the balance. See Credits and refill on update. See Credits and refill.object[] | null
Up to 50 limits, each with
name (3 to 128 characters), limit (1 or more), duration in milliseconds (1000 or more), and autoApply. The list replaces the key’s limits rather than adding to them. null or [] removes them all. See Key and identity rate limits.boolean
false suspends the key and true restores it. Not nullable. See Disabling and deleting keys.string[]
Up to 100 role names, each 1 to 128 characters. The list replaces the key’s roles. Not nullable, so send
[] to detach them all.string[]
Up to 1000 permission slugs, each 1 to 128 characters matching
^[a-zA-Z0-9_:\-\.\*]+$. The list replaces the key’s direct permissions. Not nullable, so send [] to detach them all.Credits and refill on update
The balance iscredits.remaining and the schedule is credits.refill. Clearing one sometimes clears the other:
Removing the balance removes the schedule too. Removing the schedule keeps the balance, so you can stop a subscription from renewing without taking away credits the customer already paid for.
A
refill object has interval (daily or monthly) and amount (1 or more). refillDay (1 to 31) is for monthly only. Sending it with daily, or leaving it out with monthly, fails with HTTP 400 err:unkey:application:invalid_input. (keys.createKey ignores refillDay with daily, so a body that works for create can fail here.)
To change only the balance, use keys.updateCredits.
Lists replace, they don’t merge
ratelimits, roles, and permissions are each the full list you want the key to end up with. Send every entry you want to keep, not just the new ones.
- Rate limits are matched by
name. A limit you send keeps its ID and gets the new values. A limit you leave out is deleted. - Roles must already exist. The first one that doesn’t fails the request with HTTP 404
err:unkey:data:role_not_found. - Permissions that don’t exist yet are created for you. This list only replaces the key’s direct permissions, not what its roles grant.
keys.addPermissions, keys.removePermissions, keys.addRoles, or keys.removeRoles instead. Managing key permissions compares them.
Example
Move a key to the paid plan, extend it, and stop it expiring:Response
keys.getKey to read the result.
When the change takes effect
An update applies in full or not at all, so an error leaves the key as it was. Changes take about 10 seconds to reach verification, and a few verifications just after that can still see the old settings. A new credit balance applies right away. Verifying keys has the details. Each update writes akey.update audit event, plus a permission.create event for each permission it created.
What you can’t change
You can’t changeapiId, prefix, byteLength, or recoverable after a key is created. To replace the key string while keeping the same configuration, see Rerolling keys. To start over, create a new key and delete the old one.