---
updatedAt: 2026-06-15T12:44:07.000Z
agentTools:
  projectIndex: https://docs.overledger.dev/llms.txt
---

# List the authenticated user's API keys

Returns the caller's key metadata. Secrets are never included.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Overledger Server",
    "description": "The Overledger Server is the primary client-facing gateway.\nIt handles authentication, JSON-RPC proxying to connected networks, smart contract permission\nmanagement, Flow App session orchestration, and user/node/network management.\n\n## Authentication\nRequests authenticate with **either** of two credentials, checked in this order:\n\n- **`X-API-Key` header** — an API key of the form\n  `fk_<keyId>.<secret>`. Accepted on any route and **takes precedence** over\n  the `Authorization` header when both are present.\n- **`Authorization: Bearer <jwt>`** — a Keycloak access token, verified\n  against the realm JWKS. The caller's identity is the token's `sub` claim.\n\nBoth paths resolve to the same canonical identity, so a\ntransaction submitted via `/rpc/{apiKey}` and a query made with a Bearer JWT\nfor the same user land on the same records. The `/rpc/{apiKey}` endpoint\nadditionally accepts an API key as the URL path segment, for\nwallet/ethers clients that cannot set request headers.\n\n## Flow Endpoints\nRoutes under `/flow/` return RFC 7807 Problem Details for errors\n(`Content-Type: application/problem+json`).\n\n## x402 Payment Settlement (Permit2)\n\nFlow Apps may declare a `payment` field on a step. When present, the client\nmust obtain payment terms and submit a signed Permit2 proof. End-to-end:\n\n1. **Discover the server spender.** When a session reaches a payment step,\n   the rendered `StepSpec` exposes an `X402Descriptor` (returned as the\n   `X-Payment-Required` header on `402 Payment Required`, and discoverable\n   via the app's `/metadata`). The `spender` field is the app's\n   settlement wallet — clients must approve this address in Permit2.\n2. **Sign Permit2 off-chain.** The client signs a Permit2 `SignatureTransfer`\n   authorising the spender to pull `amountAtomicUnits` of `tokenAddress` on\n   `networkId`, with a nonce and deadline.\n3. **Submit with `X-Payment`.** The client POSTs `submitStep` with the\n   base64-encoded payment proof in the `X-Payment` header, plus an\n   `Idempotency-Key` (proofs are idempotent per session+key).\n4. **Settlement on-chain.** The app invokes Permit2 from the\n   server spender, pulling the tokens to the descriptor `recipient`. The\n   receipt is returned in the `200` response body as\n   `paymentReceipt` (see [`X402SettlementReceipt`](#/components/schemas/X402SettlementReceipt))\n   and in the `X-Payment-Response` header (base64-encoded JSON of the same).\n5. **Failure modes.** Validation problems (bad signature, expired deadline,\n   insufficient allowance, descriptor mismatch) return `400`. On-chain\n   execution failures (revert, nonce exhausted, RPC errors) return `502`.\n   Both retain RFC 7807 Problem Details semantics.\n\n## App-Scoped Persistent State\n\nEach Flow App can persist a JSON document of state per user. State is\n**scoped to `(appId, userId)`** — there is no cross-user sharing; one user\ncannot see another user's state, even within the same app. State persists\nacross sessions (it outlives any single session's TTL) and is mutated by\nthe app's step handlers via patch operations.\n\nClients read app state in two ways:\n\n- **Indirectly inside a `StepSpec`** — fields and tables may carry a\n  `dataRef` such as `\"$appState.connections\"`. Overledger resolves the\n  reference for the calling user before sending the spec to the client.\n  Select / radio-group fields may additionally carry `submitResolve`,\n  which expands the chosen option back into its full record on submission\n  (see the `StepField` schema).\n- **Directly via app-defined queries** — the app registers query handlers\n  and the client calls\n  [`GET /flow/apps/{appId}/query/{queryId}`](#/paths/~1flow~1apps~1%7BappId%7D~1query~1%7BqueryId%7D/get).\n  The query handler is the app's chance to shape, filter, or paginate\n  whatever it stores. There is no generic `/appState` CRUD endpoint —\n  state is only reachable through the spec/query indirection.\n\n## Content Safety\n\nAll user-visible strings in a `StepSpec` are scanned by Overledger\nbefore being returned to the client, and rejected step specs surface as\n`502 Bad Gateway` with an RFC 7807 Problem Details body. Two filter\nlayers run on every render and submit:\n\n- **Base contract patterns** — built into the SDK and enforced\n  identically by Overledger.\n- **Operator-defined patterns** — additional literal strings configured\n  per deployment via the `CONTENT_FILTER_EXTRA_PATTERNS` environment\n  variable on Overledger.\n\n**Banned content categories:**\n\n- Prompt-injection attempts\n- Credential-harvesting language\n- HTML / script / iframe injection and inline event handlers\n- Unicode spoofing (e.g. right-to-left override, zero-width characters)\n- Profanity and slurs\n- and more\n\nThe specific patterns are intentionally not published. App authors should\ntreat any `502` whose detail mentions \"content rejected\" as a content\nfilter rejection and revise the offending copy.\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://fusion-rollup.quant.dev",
      "description": "Testnet (live) — the public Fusion Server endpoint"
    },
    {
      "url": "http://localhost:8080",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "API Keys",
      "description": "Self-service management of Overledger-issued API keys"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "A Keycloak access token (JWT), verified against the realm JWKS\n(signature / issuer / expiry). The caller's identity is the token's\n`sub` claim — this is **not** a `clientId`.\n"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "An Overledger-issued API key of the form `fk_<keyId>.<secret>`, minted via\n`POST /users/me/api-keys`. Accepted on any route and **takes precedence**\nover the `Authorization` header when both are supplied. Resolves to the\nsame identity (Keycloak `sub`) as the equivalent Bearer JWT.\n"
      }
    },
    "schemas": {
      "ApiKeyScope": {
        "type": "string",
        "description": "A capability granted to an API key. Currently only `rpc` (full JSON-RPC access).",
        "enum": [
          "rpc"
        ],
        "example": "rpc"
      },
      "ApiKeySummary": {
        "type": "object",
        "description": "A key's metadata — never includes the secret.",
        "required": [
          "keyId",
          "label",
          "scopes",
          "createdAt"
        ],
        "properties": {
          "keyId": {
            "type": "string",
            "description": "Public lookup handle — the first segment of the raw key."
          },
          "label": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last successful verification (throttled writes)."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "revokedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StandardError": {
        "type": "object",
        "required": [
          "timestamp",
          "status",
          "error",
          "message",
          "path"
        ],
        "properties": {
          "timestamp": {
            "type": "integer",
            "description": "Milliseconds since epoch"
          },
          "status": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        },
        "example": {
          "timestamp": 1709737845000,
          "status": 400,
          "error": "Bad request",
          "message": "Validation failed",
          "path": "/users/me/deposits"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized — missing or invalid credentials",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/StandardError"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/users/me/api-keys": {
      "get": {
        "tags": [
          "API Keys"
        ],
        "operationId": "listApiKeys",
        "summary": "List the authenticated user's API keys",
        "description": "Returns the caller's key metadata. Secrets are never included.",
        "responses": {
          "200": {
            "description": "The caller's API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKeySummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  }
}
```