---
title: List keys
description: List the credentials this key may administer, without their secrets.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# List keys

`GET /keys`

List the credentials this key may administer, without their secrets.

**Permission:** Cluster key, or a namespace key managing collection keys within its namespace.

[API key types and authentication](/engine/reference/authentication.md).

Lists return items and next_cursor. Keep the same key and filters for the next page. List cursors expire after one hour.

A namespace key sees collection keys within its namespace.

## Example request

```http
GET /keys HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
```

## Query parameters

### `cursor`

**string · optional · nullable**

Opaque continuation token from next_cursor. Keep the same key, filters, and other request values. Omit it for the first page.

### `limit`

**integer · optional**

Maximum resources in this page. Default 50, minimum 1, maximum 100.

Default: `50`.

- Minimum: 1
- Maximum: 100

## Responses

### 200 · Success

A page of administrable keys. Secrets are omitted.

Content type: `application/json`.

#### Response headers

##### `x-request-id`

**string · required**

Request correlation ID. Retain it when investigating a failed or unexpected request.

```json
{
  "items": [
    {
      "id": "key_01K6Q6N7D8E9F0G1H2J3K4M5N6",
      "name": "acme-read",
      "prefix": "gek_",
      "scope": {
        "kind": "namespace",
        "namespace": "acme",
        "actions": [
          "read",
          "search",
          "query"
        ]
      },
      "created_at": "2026-10-06T10:00:00Z"
    }
  ],
  "next_cursor": null
}
```

#### Response fields

##### `items`

**array<object> · required**

Page of keys visible to this key. An empty array means no resources matched.

###### `items[].created_at`

**string (date-time) · required**

Time the resource was created, as an ISO 8601 UTC timestamp.

###### `items[].id`

**string · required**

Immutable administrative key ID with the key_ prefix. This is not the secret used to authenticate.

###### `items[].name`

**string · required**

Administrative name assigned when this key was created.

###### `items[].prefix`

**string · required**

Short non-secret prefix used to identify the credential.

###### `items[].revoked_at`

**string (date-time) · optional · nullable**

Time the key was revoked. Omitted while the key remains active.

###### `items[].scope`

**object · required**

Resource scope and actions granted to this key.

###### cluster

###### `items[].scope.kind`

**"cluster" · required**

Cluster-wide authority. A cluster key can manage all namespaces and keys, and perform every data action.

###### namespace

###### `items[].scope.actions`

**array<string> · required**

Nonempty list of permitted actions. write includes read. search and query are independent and do not include read. A new key cannot exceed its creator’s actions.

- `read`: Read resources and job state.
- `write`: Create, change, and delete resources. Includes read.
- `search`: Retrieve ranked evidence from allowed collections.
- `query`: Generate cited answers from allowed collections.

###### `items[].scope.kind`

**"namespace" · required**

Namespace scope limits this key to one tenant boundary.

###### `items[].scope.namespace`

**string · required**

Name of the namespace this key can access. It cannot see resources in other namespaces.

###### collection

###### `items[].scope.actions`

**array<string> · required**

Nonempty list of permitted actions. write includes read. search and query are independent and do not include read. A new key cannot exceed its creator’s actions.

- `read`: Read resources and job state.
- `write`: Create, change, and delete resources. Includes read.
- `search`: Retrieve ranked evidence from allowed collections.
- `query`: Generate cited answers from allowed collections.

###### `items[].scope.collections`

**array<string> · required**

Nonempty list of collection names within the named namespace. The key cannot create collections or issue other keys.

- Minimum items: 1

###### `items[].scope.kind`

**"collection" · required**

Collection scope limits this key to the named collections in one namespace.

###### `items[].scope.namespace`

**string · required**

Namespace name that contains all collections in this scope.

###### `items[].secret`

**string · optional · nullable**

Credential returned only once, in the create response. Store it securely on your server. Later list responses omit it.

##### `next_cursor`

**string · required · nullable**

Token for the next page, or null when this result has no next page. Do not parse or modify the token.

## Errors

[Error format and retry guidance](/engine/reference/errors.md).

### 400 · `invalid_request`

A field, path, parameter, or conditional request rule is invalid.

Correct the request. Unknown fields are rejected.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "A field, path, parameter, or conditional request rule is invalid.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 400 · `invalid_cursor`

The cursor expired or does not belong to this request and key.

Restart from the first page. Preserve the same key, filters, and request values when continuing.

```json
{
  "error": {
    "code": "invalid_cursor",
    "message": "The cursor expired or does not belong to this request and key.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 401 · `unauthenticated`

The API key is missing, invalid, or revoked.

Send an active key in Authorization: Bearer or X-API-Key.

```json
{
  "error": {
    "code": "unauthenticated",
    "message": "The API key is missing, invalid, or revoked.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 403 · `forbidden`

The key can see the resource but lacks permission for this operation.

Use a key with the required action or scope kind.

```json
{
  "error": {
    "code": "forbidden",
    "message": "The key can see the resource but lacks permission for this operation.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

### 503 · `temporarily_unavailable`

A dependency, cluster readiness condition, or capacity limit prevents this operation.

Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

```json
{
  "error": {
    "code": "temporarily_unavailable",
    "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.",
    "request_id": "req_example",
    "retryable": true,
    "details": {}
  }
}
```

### 500 · `internal_error`

An unexpected server failure prevented this request from completing.

Retain x-request-id for investigation. Follow retryable before retrying a write.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected server failure prevented this request from completing.",
    "request_id": "req_example",
    "retryable": false,
    "details": {}
  }
}
```

## Other request languages

### cURL

```bash
curl -sS "$GRAPHON_ENGINE_URL/keys" \
  -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY"
```

### Python

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    os.environ["GRAPHON_ENGINE_URL"] + "/keys",
    headers={
        "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"],
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())
```

### JavaScript

```javascript
const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/keys", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`,
  },
});
console.log(response.status, await response.text());
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.