/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.
Authentication: Bearer API key in the Authorization header
Path parameters
org_idstringrequiredYour organization id (uuid).
GET /api/whoamireturns it.providerenumrequiredThe provider to connect.
Request body
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.
One of
object
token_idstringrequiredtoken_secretstringrequired
configobjectProvider config: required for azure_openai, bedrock, vertex and fireworks; ignored (stored empty) for key-only providers.
One of
object
endpointstringrequiredPublic 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
regionstringrequiredauth_modeenumaccess_key_idstring | null
object
project_idstringrequiredregionstringrequiredA Vertex location such as us-central1, or global.
object
account_idstringrequired
spend_secretstring | nullOptional provider ADMIN key (openai
sk-admin-, anthropicsk-ant-admin), used only for spend reads.setup_aliasstringrequiredA new, unique account handle for this provider.
Responses
200The saved account and the hookup check's verdict.
Response
connectionobjectrequiredOne connected account. Never carries ids or secrets.
connection
providerenumrequiredA 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_aliasstringrequiredAccount handle; the default account's handle is the provider name.
configobjectrequiredNon-secret provider config.
credential_last4string | nullrequiredspend_credential_last4string | nullrequiredLast four of the stored admin key, if any.
statusenumrequiredThe 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.priorityintegerrequiredPosition in the org's account pool; lower is tried first.
exhaustion_fallbackbooleanrequiredWhether the pool rotates past this account when it is quota_exhausted.
ratelimit_failoverbooleanrequiredWhether the pool rotates past this account while it is rate limited.
failover_only_onarray | nullrequiredNull for unrestricted; a list makes the account a fallback for exactly those failures.
checkobjectrequiredThe persisted verdict of one hookup check.
check
providerenumrequiredA provider an organization can connect its own key for. kenari, kiosapi, tokenharbor, groq and nvidia_nim are free-tier providers open to every plan.
statusenumrequiredThe 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 | nullrequiredProvider detail (raw code and message, remediation text).
spend_keyholds the admin key's own verdict;modelsholds per-model support facts.status_checked_atstring | nullrequiredstatus_sourceenum | nullrequired
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.Response
errorstringrequiredHuman-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.
Response
errorstringrequiredHuman-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.
Response
errorstringrequiredHuman-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).
Response
errorstringrequiredHuman-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.
Response
errorstringrequiredHuman-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.
Response
errorstringrequiredHuman-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.
Response
detailarray<object>requireddetail
typestringlocarray<string | integer>msgstring
Request
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"
}'Response
{
"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