update(id: string, patch: KeyPatch, options?: RequestScope): Promise<KeyResource>Patches a key label, enabled state, scope map or project fence. Send only the fields you want to change.
The two fields behave in opposite ways. patch.scopes merges: the map you send is layered over what is stored, so an omitted resource keeps its current level and taking a permission away means sending that resource explicitly at none. An empty map changes nothing. patch.projectIds replaces wholesale: the array you send becomes the fence, and an empty array removes the fence entirely. The merged scope map then goes through the same ceiling check and the same silent clamp to the key owner role as create, so read scopes off the response.
A key cannot re-scope, re-fence or disable itself. If id is the key making the request and the patch contains scopes, projectIds or active: false, the call fails with 409 auth.self_mutation_forbidden. Renaming yourself is allowed, and so is setting active: true on yourself, because neither can lock you out. Everything else needs a second key.
Example
const key = await envless.keys.update('0191f3c2-8a71-7c3e-9b2d-4f5a6c7d8e90', {
scopes: { variables: 'none' },
projectIds: []
})
console.log(key.scopes.variables, key.projectIds.length)Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The key id, ids only, no prefix and no slug form. |
patch.name | string | No | New label, 4 to 34 characters. |
patch.active | boolean | No | Enables or disables the key without revoking it. |
patch.scopes | Record<string, string> | No | Partial map merged over the stored scopes, send none to remove a permission. |
patch.projectIds | Array<string> | No | Replacement project fence, an empty array removes the fence. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
KeyResource for the patched key, carrying the merged and clamped scopes.
Worth knowing
- The scope ceiling and project subset checks run before the key is looked up, so an over privileged patch against an id that does not exist returns 403 instead of 404. Fix the scopes first, then trust the 404.
- Fields of the wrong type are dropped rather than rejected, and a patch that ends up touching nothing resolves with 200 and the unchanged key.
- The secret cannot be changed here. Rotation is not exposed anywhere on the public API.
Required scopes
keys:write
Underlying endpoint
PATCH /keys/{id}
Request and response schema, every error code, and a live playground.
In Python
envless.keys.update()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.keys.update
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->keys->update()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.