---
title: "List portal keys"
method: POST
path: "/v2/portal.listKeys"
tags: ["portal"]
---

# List portal keys

`POST /v2/portal.listKeys`

Retrieve a paginated list of API keys owned by the authenticated portal
session's end user.

This is the portal-scoped variant of `apis.listKeys`. It authenticates only
with a portal session cookie and always restricts results to the keys owned
by the session's external identity, within the keyspaces configured on the
portal configuration. Both the identity and the keyspaces come from the
session, so the request body has no `externalId` or `apiId` field.

## Request body

- V2PortalListKeysRequestBody
  - `limit` integer — Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.
  - `cursor` string — Pagination cursor from a previous response to fetch the next page. Use when `hasMore: true` in the previous response.

## Response `200`

Successfully retrieved paginated keys. Use the pagination cursor for additional results when `hasMore: true`.

- V2PortalListKeysResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` KeyResponseData[], required — Array of the portal end user's API keys.
    - `keyId` string, required — Unique identifier for this key.
    - `start` string, required — First few characters of the key for identification.
    - `enabled` boolean, required — Whether the key is enabled or disabled.
    - `name` string — Human-readable name for this key.
    - `meta` object — Custom metadata associated with this key.
    - `createdAt` integer, required — Unix timestamp in milliseconds when key was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when key was last updated.
    - `lastUsedAt` integer — Unix timestamp in milliseconds when key was last used for verification. This is an approximated value, accurate to within 5 minutes.
    - `expires` integer — Unix timestamp in milliseconds when key expires (if set).
    - `permissions` string[]
    - `roles` string[]
    - `credits` KeyCreditsData — Credit configuration and remaining balance for this key.
      - `remaining` integer, nullable, required — Number of credits remaining (null for unlimited).
      - `refill` KeyCreditsRefill — Configuration for automatic credit refill behavior.
        - `interval` 'daily' | 'monthly', required — How often credits are automatically refilled.
        - `amount` integer, required — Number of credits to add during each refill cycle.
        - `refillDay` integer — Day of the month for monthly refills (1-31). Only required when interval is 'monthly'. For days beyond the month's length, refill occurs on the last day of the month.
    - `identity` Identity
      - `id` string, required — Identity ID
      - `externalId` string, required — External identity ID
      - `meta` object — Identity metadata
      - `ratelimits` RatelimitResponse[] — Identity ratelimits
        - `id` string, required — Unique identifier for this rate limit configuration.
        - `name` string, required — Human-readable name for this rate limit.
        - `limit` integer, required — Maximum requests allowed within the time window.
        - `duration` integer, required — Rate limit window duration in milliseconds.
        - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.
    - `plaintext` string — Decrypted key value (only when decrypt=true).
    - `ratelimits` RatelimitResponse[]
      - `id` string, required — Unique identifier for this rate limit configuration.
      - `name` string, required — Human-readable name for this rate limit.
      - `limit` integer, required — Maximum requests allowed within the time window.
      - `duration` integer, required — Rate limit window duration in milliseconds.
      - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.
  - `pagination` Pagination, required — Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string — Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required — Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/e171c13af8aa/schema)