ai
POST /v1/ai/credentials
Store an AI provider key for this organization.
Ìfàṣẹ́pọ̀
Fi bọ́ọ̀lù (bearer token) ranṣẹ gẹ́gẹ́ bí kọ́kọ́rọ́ API. Kọ́kọ́rọ́ náà gbọ́dọ̀ ní ìyọ̀ǹda billing.payment.manage; a ó kọ̀ ọ́ silẹ pẹlu 403, kii ṣe 404, ti kọ́kọ́rọ́ náà kò bá ní i.
Ibùdó àmì ìdánimọ̀ ilé-iṣẹ́ rẹ sí
Ibi-iwọle yii n gba org_id gẹgẹ bi aaye ninu ara JSON naa.
Id àjọ rẹ wa lórí ojú-ìwákòòkò àwọn bọ́tìnnì API nínú daṣibọọdú rẹ, lẹ́gbẹ̀ẹ́ bọ́tìnnì náà gan-an. Ó jẹ́ ìd kan náà nínú gbogbo ìpè tí o bá ṣe.
Gbiyanju rẹ
Rọ́pọ̀ èyíkéyìí nínú àwọn àmì ìtọ́ka < > pẹ̀lú iye tirẹ̀, àti àmì ìdánimọ̀ bọ́tìnnì náà pẹ̀lú bọ́tìnnì kan láti inú dásibọ̀ọ̀dù rẹ.
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> }'Ṣé o ti wọlé? Iwọ̀n api ní nú ìgbékalẹ̀ rẹ kún id àjọ gidi rẹ ati bọtini tirẹ, o si nṣiṣẹ ibeere na lòdì si api gidi ki o le rii esi gidi na. Ṣí ojú abáná yìí sílẹ̀ nínú kọnsólù API
Àwọn kúlẹ̀kúlẹ̀
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.payment.manage.
Akoonu ibeere naa
| Orúkọ | Iru | Tí a nílò | Kini o jẹ |
|---|---|---|---|
provider | AiProviderCode | Bẹẹni | 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 | Bẹẹni | The key itself. Written straight to Vault and never returned. |
label | string | Bẹẹkọ | — |
org_id | Uuid | Bẹẹkọ | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
Idahun
| Orúkọ | Iru | Tí a nílò | Kini o jẹ |
|---|---|---|---|
id | Uuid | Bẹẹni | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
provider | AiProviderCode | Bẹẹni | 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 | Bẹẹni | — |
state | string<untested, working, broken> | Bẹẹkọ | 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 | Bẹẹkọ | 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 | Bẹẹkọ | — |
tested_on_save | boolean | Bẹẹkọ | 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 | Bẹẹkọ | 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 | Bẹẹkọ | 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… |
verified_at | object | Bẹẹkọ | 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 | Bẹẹkọ | — |
created_at | string | Bẹẹni | — |
Awọn aṣiṣe ti ibudo ipari yii le da pada
401 · 403 · 422 · 429