인증
Bearer 토큰으로 API 키를 전송하세요. 키는 반드시 billing.manage 권한을 가지고 있어야 하며, 권한이 없는 키는 404가 아닌 403으로 거부됩니다.
조직 ID가 들어가는 위치
이 엔드포인트는 JSON 본문의 필드로 org_id을(를) 받습니다.
조직 ID는 대시보드의 API 키 화면에서 키 바로 옆에 있습니다. 이는 실행하는 모든 호출에서 동일한 ID입니다.
무료 체험하기
대괄호 안에 있는 모든 내용을 사용자 지정 값으로 바꾸고, 키 플레이스홀더는 대시보드의 키로 바꾸세요.
curl -X POST https://api.zinndigital.com/v1/ai/credentials \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "provider": <AiProviderCode>, "api_key": <string> }'로그인하셨나요? 대시보드의 API 콘솔이 실제 조직 ID와 본인의 키를 자동으로 채우고 라이브 API를 대상으로 요청을 실행하므로 실제 응답을 확인할 수 있습니다. API 콘솔에서 이 엔드포인트를 여세요
상세 정보
Puts the key in Vault and records a pointer. Any existing live key for the same provider is revoked in the same transaction — one live key per provider, because two is not a richer model, it is an ambiguity about which key we are about to spend the customer's money through. ⚖️ **The key is TESTED before this responds** — owner instruction 2026-08-20: *"we need to test the api keys when they add them."* A **real** completion with our own prompts and tool format, not the free authentication probe: the narrower question is one a screen would render as a green tick while a recipe fails on its first run. The response carries `state`, `last_error` and `tested_on_save`. ⛔⛔ **A FAILED TEST DOES NOT FAIL THE SAVE.** The key is already in Vault by then. Refusing would leave a customer who pasted a valid key with an empty screen and no way to tell "we could not reach the provider" from "you typed it wrong", while the secret sat stored. They get it saved, the state set honestly, and the provider's own reason to act on. A `422` still means nothing was stored anywhere. ⭐ The provider's model catalogue is also filled from this key in the same call — a free authenticated read that costs the customer nothing, and the only opportunity we get for a vendor we hold no platform key for. ⛔ Vault is written **before** the row, and the row is created only if that succeeded. A `422` means nothing was stored anywhere: an unreachable secret store is a refusal, never a silent skip that leaves the customer believing their key was saved. Requires `billing.manage`.
요청 본문
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
provider | AiProviderCode | 예 | An LLM vendor a customer may bring their own key for. `xai` was added by W24-G on the owner's 2026-08-20 instruction naming Grok alongside Claude and ChatGPT. |
api_key | string | 예 | The key itself. Written straight to Vault and never returned. |
label | string | 아니요 | — |
org_id | Uuid | 아니요 | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
응답
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
id | Uuid | 예 | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
provider | AiProviderCode | 예 | An LLM vendor a customer may bring their own key for. `xai` was added by W24-G on the owner's 2026-08-20 instruction naming Grok alongside Claude and ChatGPT. |
label | string | 예 | — |
state | string<untested, working, broken> | 아니요 | Whether the key is known to work. ⛔ Three values, not two: "we have never tried it" and "we tried it and it failed" must not collapse, because telling a customer their valid key… |
last_checked_at | object | 아니요 | When we last *asked*, whatever the answer — distinct from `verified_at`, which is when it last *worked*. A key checked five minutes ago and broken has a recent `last_checked_at`… |
broken_since | object | 아니요 | — |
tested_on_save | boolean | 아니요 | Only on the response to `addAiCredential`. Whether the on-save test actually **ran** — ⛔ not whether it passed. `false` means we could not even try, which is `untested` and not… |
last_error | string | 아니요 | The provider's own reason, trimmed, for the customer to act on. "Your credit balance is too low" needs a different response from "this key was revoked". |
failure | VendorFailure | null | 아니요 | What the customer is told about the last failure, and where they may be sent (CLAUDE.md §57). `null` when the key works or has never been tried — ⛔ which is not the same as "fin… |
verified_at | object | 아니요 | The last time a real call on this key succeeded. ⛔ `null` means **never proven**, not broken — telling a customer their valid key is invalid is worse than saying nothing. |
last_used_at | object | 아니요 | — |
created_at | string | 예 | — |
이 엔드포인트가 반환할 수 있는 오류
401 · 403 · 422 · 429