# Key info

> GET /key 레퍼런스입니다. 키 자체로 그 키의 조직, 프로젝트, 상태, 지출 한도, 만료, 사용액을 조회합니다. 에러 본문은 {message, code} 형식이고, 거부되는 키는 모두 401을 받습니다.

Source: https://kiln.bricksum.com/docs/ko/api-reference/key

`GET https://api.bricksum.com/v1/key`

호출에 사용한 API 키의 조직, 프로젝트, 상태, 지출 한도, 만료, 지금까지의 사용액을 반환합니다. 콘솔 계정 없이 키를 확인하는 방법이며, 키를 가진 팀원이 자기 키를 조회할 수 있습니다. 평문 키와 그 해시는 응답에 포함되지 않습니다.

지출 한도와 월 예산의 동작은 [사용량과 과금](https://kiln.bricksum.com/docs/ko/usage-billing) 페이지에서 설명합니다.

Base URL, 나머지 엔드포인트, 공통 제한은 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 있습니다.

## 인증

API 키 자체를 Bearer 토큰으로 보냅니다(Authorization: Bearer sk-bk-your-key). 이 경로의 신원은 키이므로 콘솔 세션 토큰은 받지 않습니다. 이 엔드포인트는 추론 게이트웨이에 속하지 않습니다. Kiln API가 직접 처리하며, 키를 해시로 조회해 활성 키로 확인되지 않는 요청에는 401을 반환합니다.

## 요청

| 상태 | 설명 |
| --- | --- |
| 지원 | 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다. |
| 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| 무시됨 | 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다. |
| 미지원 | 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다. |

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `Authorization` | header | 필수 |  | 지원 | API 키를 담은 Bearer 토큰입니다(예: Authorization: Bearer sk-bk-your-key). 조회 전에 키 접두사와 길이를 검사하므로, 콘솔 세션 토큰(JWT)은 401(unauthorized)로 거부됩니다. |
| `x-api-key` | header |  |  | 미지원 | 이 경로에서는 읽지 않습니다. x-api-key만 보낸 요청은 값이 올바른 키여도 401(unauthorized)로 거부됩니다. Authorization을 사용하세요. |
| `x-org-id` | header |  |  | 무시됨 | 신원 헤더인 x-org-id, x-project-id, x-api-key-id는 이 경로에서 게이트웨이가 제거합니다. 응답의 조직과 프로젝트는 헤더가 아니라 키에서 정해집니다. |
| `query string` | string |  |  | 무시됨 | 이 엔드포인트는 파라미터를 받지 않습니다. 쿼리 문자열은 수락되지만 응답에 영향을 주지 않습니다. |

Authorization 헤더의 키가 조회 대상을 정합니다. 그 밖에 보낼 것은 없습니다.

## 응답 본문

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | 키 ID(UUID)입니다. 콘솔의 키 목록에도 같은 ID가 표시됩니다. |
| `org_id` | string | 키가 속한 조직의 ID입니다. 이 키의 사용량은 해당 조직에 과금됩니다. |
| `project_id` | string | 키가 속한 프로젝트의 ID입니다. |
| `name` | string | 콘솔에서 키에 붙인 이름입니다. |
| `prefix` | string | 키 접두사(sk-bk-)입니다. 모든 키가 같은 값을 갖습니다. |
| `last4` | string | 키의 마지막 네 글자입니다. 목록에서 키를 구분할 때 씁니다. 전체 키는 생성 직후 한 번만 표시되며 이후에는 조회할 수 없습니다. |
| `status` | string | 키 상태입니다. 성공 응답에는 "active"가 담깁니다. 정지되거나 폐기된 키는 대신 401을 받습니다. |
| `spend_limit_usd` | number \| null | 이 키의 지출 한도이며 단위는 USD입니다. null이면 키 자체의 한도가 없습니다. 한도에 도달하면 이 키의 추론 요청은 402로 거부됩니다. |
| `expires_at` | string \| null | 만료 시각이며 RFC 3339 형식입니다. 만료가 없으면 null입니다. 그 시각부터 이 엔드포인트와 추론 엔드포인트 모두에서 키는 401을 받습니다. |
| `usage_usd` | number | 이 키에 기록된 사용액이며 단위는 USD입니다. 키의 usage 이벤트를 합산한 값이고, 지출 한도는 이 값과 비교합니다. |
| `last_used_at` | string \| null | 게이트웨이가 이 키를 마지막으로 통과시킨 시각이며 RFC 3339 형식입니다. 사용 이력이 없으면 null입니다. 게이트웨이가 요청 처리 경로 밖에서 기록하므로, 방금 한 호출은 아직 반영되지 않을 수 있습니다. |
| `created_at` | string | 키를 만든 시각이며 RFC 3339 형식입니다. |

## 에러

이 엔드포인트는 추론 게이트웨이가 아니라 Kiln API가 처리하므로, 에러 본문은 {"error": {"message", "code"}} 형식입니다. type과 param 필드는 없고, error.code는 unauthorized 같은 짧은 문자열입니다. 메시지 문구가 아니라 HTTP 상태와 error.code로 분기하세요.

| 상태 | error.code | 원인 | 조치 |
| --- | --- | --- | --- |
| 401 | `unauthorized` | Authorization 헤더가 없거나, Bearer 토큰이 아니거나, 값이 API 키 형식이 아닙니다. 콘솔 세션 토큰도 여기에 해당합니다. 메시지는 API key required입니다. | 콘솔에서 만든 API 키를 Authorization: Bearer로 보내세요. |
| 401 | `unauthorized` | 키가 등록되어 있지 않거나, 활성 상태가 아니거나(정지 또는 폐기), 만료 시각이 지났습니다. 세 경우 모두 invalid API key 메시지와 함께 같은 401을 반환하므로, 응답만으로는 어느 경우인지 알 수 없습니다. | 콘솔에서 키의 상태와 만료일을 확인하거나 새 키를 만드세요. |
| 429 |  | 이 경로에 걸린 게이트웨이 공용 한도입니다. 조직별이 아니라 전체 호출자를 합쳐 세며, 게이트웨이가 직접 만드는 응답이라 위 에러 형식을 따르지 않고 본문이 없을 수도 있습니다. | 잠시 기다렸다가 다시 시도하세요. 본문을 파싱하지 말고 상태 코드만으로 분기하세요. |
| 500 | `internal` | 키 저장소를 읽지 못했습니다. 메시지는 internal error입니다. | 잠시 기다린 뒤 재시도하고, 상태 페이지를 확인하세요. |

전체 상태 코드는 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지에 있습니다.

## 제한

- 과금: 과금되지 않습니다. 이 엔드포인트는 추론을 실행하지 않으므로 usage 이벤트를 발행하지 않으며, usage_usd도 변하지 않습니다.
- 범위: 응답은 Authorization 헤더에 담긴 키 하나만 설명합니다. 이 인증 방식으로 조직의 키 목록을 조회하는 엔드포인트는 없습니다.
- 레이트 리밋: 게이트웨이가 이 경로에 공용 한도를 적용하며, 조직별이 아니라 전체 호출자를 합쳐 셉니다. 이 한도에 걸린 429는 게이트웨이가 만들기 때문에 본문 형식이 위 설명과 다릅니다.
- 이 엔드포인트를 지원하는 SDK는 없습니다. OpenAI나 Anthropic API에 속하지 않으므로 해당 SDK에 메서드가 없습니다. HTTP 클라이언트로 직접 호출하세요.

429의 헤더와 재시도 방법은 [레이트 리밋](https://kiln.bricksum.com/docs/ko/rate-limits) 페이지에 있습니다.

## 예제

### 요청

**cURL**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer $KILN_API_KEY"
```

### 응답

**200 OK**
```json
{
  "id": "6f1c2e7a-3c4d-4a10-9a2b-0f5c8d7e1234",
  "org_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
  "project_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
  "name": "production",
  "prefix": "sk-bk-",
  "last4": "9f3c",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": "2027-01-01T00:00:00Z",
  "usage_usd": 12.34,
  "last_used_at": "2026-09-18T07:21:03Z",
  "created_at": "2026-06-01T09:00:00Z"
}
```

**401 Unauthorized**
```json
{
  "error": {
    "message": "invalid API key",
    "code": "unauthorized"
  }
}
```