API keys

envless.keys.list()

List API keys in the workspace

ts
list(options?: SortedListOptions): Promise<Page<KeyResource>>

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. options.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. options.search matches name and prefix and nothing else.

Example

ts
const page = await envless.keys.list({ search: 'ci', limit: 50, order: 'desc' })

for (const key of page.items) {
    console.log(key.prefix, key.active, key.lastUsedAt)
}

Parameters

ParameterTypeRequiredDescription
options.limitnumberNoRows per page, a whole number from 1 to 100.
options.offsetnumberNoWhole number of keys to skip before the page starts.
options.searchstringNoCase insensitive substring match against name and prefix.
options.orderstringNoDefaults to name, which sorts A to Z. Pass asc for oldest first or desc for newest first on createdAt.
options.signalAbortSignalNoCancels the request.

Returns

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

Reads the keys collection. list returns one page as { items, pagination }, listAll collects every page into an array, and iterate streams one item at a time without buffering the whole set.

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 keys.get(), keys.update() and keys.delete(). 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 Python

envless.keys.list()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.keys.list

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->keys->list()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.