/api/orgs/{org_id}/provider-connections/{provider}Add a provider account
Create-only: adds a new account under an explicit, unique setup_alias and never replaces an existing one (409 account_exists; list accounts first and pick another handle). The secret goes straight to the vault and the hookup check runs in the same round trip, so the response carries the verdict. A new connection needs Pro (402 pro_required) unless the org already holds a paid provider connection or the provider is a free-tier one (kenari, kiosapi, tokenharbor, groq, nvidia_nim). Needs an org admin, or any key of the org itself.
認証: AuthorizationヘッダーにBearer形式のAPIキー
パスパラメータ
org_idstring必須Your organization id (uuid).
GET /api/whoamireturns it.providerenum必須The provider to connect.
リクエストボディ
secretstring | object | nullThe provider credential, sent to the vault and never returned. Modal takes a token pair. May be omitted only to edit an existing azure_openai account's deployments.
いずれか
object
token_idstring必須token_secretstring必須
configobjectProvider config: required for azure_openai, bedrock, vertex and fireworks; ignored (stored empty) for key-only providers.
いずれか
object
endpointstring必須Public https URL of the Azure AI Foundry resource.
api_versionstring | nulldeploymentsobjectCatalog model slug (or Azure wire id) to your deployment name. At least one entry is required. Stored re-keyed by wire id.
object
regionstring必須auth_modeenumaccess_key_idstring | null
object
project_idstring必須regionstring必須A Vertex location such as us-central1, or global.
object
account_idstring必須
spend_secretstring | nullOptional provider ADMIN key (openai
sk-admin-, anthropicsk-ant-admin), used only for spend reads.setup_aliasstring必須A new, unique account handle for this provider.
レスポンス
200The saved account and the hookup check's verdict.
レスポンス
connectionobject必須One connected account. Never carries ids or secrets.
connection
providerenum必須A provider an organization can connect its own key for. kenari, kiosapi, tokenharbor, groq and nvidia_nim are free-tier providers open to every plan.
setup_aliasstring必須Account handle; the default account's handle is the provider name.
configobject必須Non-secret provider config.
credential_last4string | null必須spend_credential_last4string | null必須Last four of the stored admin key, if any.
statusenum必須The provider-verified key state, written by the hookup check and by real traffic.
provider_errormeans the provider was unreachable when checked, not that the key is bad.priorityinteger必須Position in the org's account pool; lower is tried first.
exhaustion_fallbackboolean必須Whether the pool rotates past this account when it is quota_exhausted.
ratelimit_failoverboolean必須Whether the pool rotates past this account while it is rate limited.
failover_only_onarray | null必須Null for unrestricted; a list makes the account a fallback for exactly those failures.
checkobject必須The persisted verdict of one hookup check.
check
providerenum必須A provider an organization can connect its own key for. kenari, kiosapi, tokenharbor, groq and nvidia_nim are free-tier providers open to every plan.
statusenum必須The provider-verified key state, written by the hookup check and by real traffic.
provider_errormeans the provider was unreachable when checked, not that the key is bad.status_detailobject | null必須Provider detail (raw code and message, remediation text).
spend_keyholds the admin key's own verdict;modelsholds per-model support facts.status_checked_atstring | null必須status_sourceenum | null必須
spend_errorstring | nullSet when the serving key was saved but the admin key was not; retry with PUT and the same setup_alias.
400Unknown provider, a handle that is not a slug, malformed config, or a secret that is knowably not this provider's key.
codenames the common mistakes:platform_key_in_provider_slot(an Experientialxpl_key pasted as the provider key),not_an_api_key,wrong_provider_key,admin_key_in_main_slot,invalid_vertex_credential.レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
401Missing, unknown or revoked API key.
レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
402A Free organization's first paid provider connection needs Pro.
レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
403The key is valid but may not perform this action (for example an inference key on a provisioning-key route, or a feature outside your plan).
レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
404The resource does not exist or belongs to another organization.
レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
409An account with this handle already exists for the provider.
レスポンス
errorstring必須Human-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
422The body or query failed validation.
レスポンス
detailarray<object>必須detail
typestringlocarray<string | integer>msgstring
リクエスト
curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"setup_alias": "openai-main",
"secret": "sk-proj-EXAMPLEa1b2c3d4e5f6x9Qa"
}'レスポンス
{
"connection": {
"provider": "openai",
"setup_alias": "openai-main",
"config": {},
"credential_last4": "x9Qa",
"spend_credential_last4": null,
"status": "valid",
"priority": 0,
"exhaustion_fallback": true,
"ratelimit_failover": true,
"failover_only_on": null
},
"check": {
"provider": "openai",
"status": "valid",
"status_detail": {
"http_status": 200
},
"status_checked_at": "2026-11-19T14:02:11.482Z",
"status_source": "hookup_check"
},
"spend_error": null
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai