---
title: "Search and filter API keys"
method: POST
path: "/api/v1/api-keys/search"
tags: ["api-keys"]
---

# Search and filter API keys

`POST /api/v1/api-keys/search`

Search API keys with flexible filtering, sorting, and pagination. Supports filtering by username (admin-only), subscription name, status, sorting by multiple fields, and pagination.

## Request body

- object
  - `filters` object
    - `username` string — Filter by username (admin-only)
    - `subscription` string — Filter by subscription. Matches the subscription id on the key
    - `status` string[] — Filter by status (active, revoked, expired). Defaults to active only.
  - `sort` object
    - `by` 'created_at' | 'expires_at' | 'last_used_at' | 'name' — Field to sort by
    - `order` 'asc' | 'desc' — Sort order
  - `pagination` object
    - `limit` integer
    - `offset` integer

## Response `200`

OK response.

- ApiKeyListResponse
  - `object` string, required — Object type, always "list"
  - `data` ApiKey[], required — Array of API key metadata objects
    - `id` string, required — Unique identifier for the API key
    - `name` string, required — User-friendly name for the API key
    - `description` string — Optional description providing context about the key's purpose
    - `username` string — Username that owns this API key
    - `groups` string[] — User's groups at creation time (immutable snapshot for authorization)
    - `creationDate` string, date-time, required — When the API key was created
    - `expirationDate` string, date-time — When the API key expires (empty for permanent keys)
    - `status` 'active' | 'revoked' | 'expired', required — Current status of the API key
    - `lastUsedAt` string, date-time — When the API key was last used for validation
    - `subscription` string — Name of the subscription associated with this API key
  - `has_more` boolean, required — Whether there are more results beyond this page
  - `subscriptionDetails` object — Map of subscription name to its details (model names). Populated by the BFF by fetching MaaSSubscription resources for any subscription values found on the returned API keys.

## Other responses

- `400` — Bad Request. Invalid search parameters.
- `401` — Unauthorized response.
- `500` — Internal Server Error

## Changes

- **2026-05-20** `b3ad944dcccc` — 1 info
  - added the new optional request property `filters/subscription`
- **2026-04-02** `8e51c16ea9dc` — 2 info
  - added the optional property `data/items/subscription` to the response with the `200` status
  - added the optional property `subscriptionDetails` to the response with the `200` status
- **2026-03-16** `9380b41a2304` — 1 info
  - endpoint added
- **2026-02-02** `232174554498` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/changes/api/v1/api-keys/search/post.md)

---

[API](https://skmtc.dev/opendatahub-io/apis/maas-bff-api.md) · [All operations](https://skmtc.dev/opendatahub-io/apis/maas-bff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opendatahub-io/maas-bff-api/revisions/e73195b504df/schema)