/api/orgs/{org_id}/provider-connections/{provider}Rotate a provider account
Replaces the credential (and config) of the account named by setup_alias; with setup_alias omitted it connects or rotates the provider-named default account. Runs the hookup check inline. Rotating needs no Pro once the org holds a paid connection; connecting a first one through PUT is gated like POST (402 pro_required). For azure_openai, omit secret to edit only the deployments map with the stored key (endpoint and api version must stay the same, else 400 secret_required_for_endpoint). A spend_error in the response means the serving key was saved but the admin key was not: retry with PUT.
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_aliasstring | nullAccount handle (lowercase letters, digits, - or _, 1 to 63 chars). Omitted, the provider-named default account.
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).
409custom_endpoint_account_immutable: a custom endpoint account cannot be rotated, create a new account instead.connection_changed: the Azure account changed while saving, reload and save again.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 PUT 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": "azure-prod",
"secret": "4f1c9e2a7b3d8c6e0a5f2b9d1e7c3a8f",
"config": {
"endpoint": "https://acme-foundry.openai.azure.com",
"api_version": "2025-04-01-preview",
"deployments": {
"gpt-6-luna": "acme-luna-prod"
}
}
}'Response
{
"connection": {
"provider": "azure_openai",
"setup_alias": "azure-prod",
"config": {
"endpoint": "https://acme-foundry.openai.azure.com",
"api_version": "2025-04-01-preview",
"deployments": {
"gpt-6-luna-2026-08": "acme-luna-prod"
}
},
"credential_last4": "3a8f",
"spend_credential_last4": null,
"status": "valid",
"priority": 0,
"exhaustion_fallback": true,
"ratelimit_failover": true,
"failover_only_on": null
},
"check": {
"provider": "azure_openai",
"status": "valid",
"status_detail": {
"http_status": 200
},
"status_checked_at": "2026-11-19T14:05:40.019Z",
"status_source": "hookup_check"
},
"spend_error": null
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai