---
title: "Get one key"
method: GET
path: "/client/keys/{id}"
tags: ["Keys"]
---

# Get one key

`GET /client/keys/{id}`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/keys/{id}`
- Auth: HTTP bearer

Full key detail: settings, spend windows (total/today/week/month), and budget status. Never returns key plaintext. Requires `keys:read`.

## Path parameters

- `id` string, uuid, required

## Response `200`

Key detail

- ApiKeyDetail
  - `key` ApiKeyRecord, required
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `prefix` string, required: The visible head of the key — enough to identify it, never enough to use it
    - `projectId` string, uuid, nullable, required
    - `scopes` string[], required
    - `expiresAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `spendLimitUsd` string, nullable, required: null = no cap on this key
    - `budgetPeriod` 'day' | 'week' | 'month' | 'total', required
    - `hardCap` boolean, required: A PREFERENCE, and on its own it protects nothing: true = refuse at the cap, false = only alert — but either way it does nothing until `spendLimitUsd` is set. Read `capped` for the question "will this key actually be stopped".
    - `revoked` string, date-time, nullable, required
    - `disabledAt` string, date-time, nullable, required: Paused by its owner — reversible, unlike `revoked`
    - `lastUsedAt` string, date-time, nullable, required
    - `alertAtPct` integer, required: Percent of the cap at which the budget starts alerting
    - `rateLimitPerMin` integer, nullable, required
    - `mcp` McpKeyLabel, required
      - `app` string, required: The assistant app, e.g. Claude
      - `person` string, required: Whose connection it is
      - `personId` string, required: That person’s user id, to tell your own connections from a teammate’s
      - `revokedAutomatically` 'unused' | 'connection_gone' | 'null', nullable, required: Why it was revoked automatically, when it was: unused for 90 days, or the connection is gone. Null when it is live or an admin revoked it.
    - `setupCode` 'pending' | 'used' | 'expired' | 'null', nullable, required: For a key delivered by a one-time setup code (`delivery: setup_code`): whether an agent has spent the code yet, or it expired unspent. Null for a key that was revealed instead.
  - `usage` KeySpend, required
    - `total` string, required: Decimal USD as a string
    - `requests` integer, required
    - `today` string, required: Decimal USD as a string
    - `week` string, required: Decimal USD as a string
    - `month` string, required: Decimal USD as a string
  - `budget` BudgetStatus, required
    - `scope` 'client' | 'project' | 'key', required
    - `id` string, uuid, required
    - `name` string: Absent for an unnamed key
    - `spendLimitUsd` number, required
    - `budgetPeriod` 'day' | 'week' | 'month' | 'total', required
    - `hardCap` boolean, required
    - `alertAtPct` integer, required
    - `periodStart` string, date-time, required
    - `spendUsd` number, required
    - `pctUsed` number, nullable, required
    - `state` 'ok' | 'alerting' | 'exceeded', required

## Other responses

- `404`: No such key

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)