php

/**
 * @param KeyPatch $patch
 * @return KeyResource
 */
public function update(
    string $id,
    array $patch,
    int|float|null $timeout = null,
): array

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

php

use Envless\Envless;

$envless = new Envless();

$key = $envless->keys->update('0191f3c2-8a71-7c3e-9b2d-4f5a6c7d8e90', [
    'scopes' => ['variables' => 'none'],
    'projectIds' => [],
]);

echo $key['scopes']['variables'] ?? 'none', PHP_EOL;

Parameters

Parameter	Type	Required	Description
`$id`	`string`	Yes	The key id, ids only, no prefix and no slug form.
`$patch`	`KeyPatch`	Yes	The fields below, as one array.
`$patch['name']`	`string`	No	New label, 4 to 34 characters.
`$patch['active']`	`bool`	No	Enables or disables the key without revoking it.
`$patch['scopes']`	`array<string, string>`	No	Partial map merged over the stored scopes, send `none` to remove a permission.
`$patch['projectIds']`	`list<string>`	No	Replacement project fence, an empty array removes the fence.
`$timeout`	`int\|float`	No	Seconds each attempt of this call may take, the response body included, before it throws `Envless\Exception\NetworkException` with `isTimeout()` true. Overrides the client's `timeout` for this call, and `0` turns the limit off.

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 returns 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 TypeScript

envless.keys.update()

The same method in @goenvless/sdk, with the same request, retries and errors.

Example#

Parameters#

Returns#

Worth knowing#

Required scopes#

Underlying endpoint#