POST `/v1/ai/credentials`

Store an AI provider key for this organization.

Authentification

Envoyez une clé API en tant que jeton du porteur. La clé doit posséder l'autorisation billing.manage ; une clé qui ne l'a pas est refusée avec le code 403, et non 404.

Où insérer l'ID de votre organisation

Cet endpoint prend org_id comme champ dans le corps JSON.

L'identifiant de votre organisation se trouve sur l'écran des clés API de votre tableau de bord, à côté de la clé elle-même. Il s'agit du même identifiant pour chaque appel que vous effectuez.

Essayer

Remplacez tout ce qui se trouve entre crochets par vos propres valeurs, et le espace réservé à la clé par une clé de votre tableau de bord.

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> }'

Connecté ? La console d'API de votre tableau de bord saisit votre véritable ID d'organisation ainsi que votre propre clé, et exécute la requête sur l'API de production afin que vous puissiez voir la réponse réelle. Ouvrir ce point de terminaison dans la console API

Détails

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`.

Corps de la requête

Nom	Type	Obligatoire	Qu'est-ce que c'est
`provider`	`AiProviderCode`	Oui	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`	Oui	The key itself. Written straight to Vault and never returned.
`label`	`string`	Non	—
`org_id`	`Uuid`	Non	UUIDv7 identifier — sortable by creation time (docs/02 §8).

Réponse

Nom	Type	Obligatoire	Qu'est-ce que c'est
`id`	`Uuid`	Oui	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`provider`	`AiProviderCode`	Oui	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`	Oui	—
`state`	`string<untested, working, broken>`	Non	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`	Non	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`	Non	—
`tested_on_save`	`boolean`	Non	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`	Non	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`	Non	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`	Non	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`	Non	—
`created_at`	`string`	Oui	—

Erreurs que cet point de terminaison peut renvoyer

401 · 403 · 422 · 429