API keys

$envless->keys->list()

List API keys in the workspace

php
/** @return Page<KeyResource> */
public function list(
    ?int $limit = null,
    ?int $offset = null,
    ?string $search = null,
    ?string $order = null,
    int|float|null $timeout = null,
): Page

Returns one page of the workspace API keys. No read ever exposes a secret or its hash, so the only identifying value on a row is prefix, the non secret leading characters of the credential. Match on that when you need to line a row up against a key you already hold.

Revoked keys are soft-deleted and are excluded from this list permanently, so the page counts live keys only and never doubles as an audit trail.

Ordering defaults to name, A to Z. order: set to asc or desc switches to createdAt, oldest or newest first, and any other value, including a typo, falls back to name order without complaint. search: matches name and prefix and nothing else.

Example

php
use Envless\Envless;

$envless = new Envless();

$page = $envless->keys->list(search: 'ci', limit: 50, order: 'desc');

foreach ($page->items as $key) {
    $state = $key['active'] ? 'active' : 'revoked';

    echo "{$key['prefix']} {$state} {$key['lastUsedAt']}", PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$limitintNoRows per page, a whole number from 1 to 100.
$offsetintNoWhole number of keys to skip before the page starts.
$searchstringNoCase insensitive substring match against name and prefix.
$orderstringNoDefaults to name, which sorts A to Z. Pass asc for oldest first or desc for newest first on createdAt.
$timeoutint|floatNoSeconds 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

Page<KeyResource> with items and a pagination envelope counting the full filtered set.

Reads the keys collection. list returns one page as an Envless\Result\Page with items and pagination, listAll collects every page into an array, and iterate returns a Generator that yields one item at a time, fetching the next page only when the loop gets there.

Worth knowing

  • A key fenced to specific projects cannot call this at all. The endpoint refuses it with 403 auth.key_project_restricted, and so do $envless->keys->get(), $envless->keys->update() and $envless->keys->delete(). $envless->keys->create() is the only key method a fenced key keeps, and there projectIds must be a non empty subset of the caller's own fence. Reading the list needs a key with no fence.
  • Holding keys:read does not open the route for a fenced key. The scope is checked first, so a fenced key without it sees 403 auth.scope_missing and a fenced key with it sees 403 auth.key_project_restricted.
  • prefix is safe to log. scopes on each row is the effective map after clamping, not what was requested.

Required scopes

keys:read

Underlying endpoint

GET /keys

Request and response schema, every error code, and a live playground.

In TypeScript

envless.keys.list()

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