PUT/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.

認証: AuthorizationヘッダーにBearer形式のAPIキー

パスパラメータ

  • org_idstring必須

    Your organization id (uuid). GET /api/whoami returns it.

  • providerenum必須

    The provider to connect.

    "openai""anthropic""azure_openai""openrouter""gemini""bedrock""fireworks""modal""vertex""zai""qwen""tencent""meta""cerebras""wafer""huawei""mistral""dashscope""xai""deepseek""typesafe""kenari""kiosapi""tokenharbor""groq""nvidia_nim"

リクエストボディ

  • secretstring | object | null

    The 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必須
  • configobject

    Provider 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 | null
    • deploymentsobject

      Catalog 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_modeenum
      "access_key_pair""api_key"
      デフォルト: "access_key_pair"
    • access_key_idstring | null

    object

    • project_idstring必須
    • regionstring必須

      A Vertex location such as us-central1, or global.

    object

    • account_idstring必須
  • spend_secretstring | null

    Optional provider ADMIN key (openai sk-admin-, anthropic sk-ant-admin), used only for spend reads.

  • setup_aliasstring | null

    Account handle (lowercase letters, digits, - or _, 1 to 63 chars). Omitted, the provider-named default account.

レスポンス

  • 200

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

        "openai""anthropic""azure_openai""openrouter""gemini""bedrock""fireworks""modal""vertex""zai""qwen""tencent""meta""cerebras""wafer""huawei""mistral""dashscope""xai""deepseek""typesafe""kenari""kiosapi""tokenharbor""groq""nvidia_nim"
      • 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_error means the provider was unreachable when checked, not that the key is bad.

        "unchecked""valid""invalid""rate_limited""quota_exhausted""provider_error"
      • 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.

        "openai""anthropic""azure_openai""openrouter""gemini""bedrock""fireworks""modal""vertex""zai""qwen""tencent""meta""cerebras""wafer""huawei""mistral""dashscope""xai""deepseek""typesafe""kenari""kiosapi""tokenharbor""groq""nvidia_nim"
      • statusenum必須

        The provider-verified key state, written by the hookup check and by real traffic. provider_error means the provider was unreachable when checked, not that the key is bad.

        "unchecked""valid""invalid""rate_limited""quota_exhausted""provider_error"
      • status_detailobject | null必須

        Provider detail (raw code and message, remediation text). spend_key holds the admin key's own verdict; models holds per-model support facts.

      • status_checked_atstring | null必須
      • status_sourceenum | null必須
    • spend_errorstring | null

      Set when the serving key was saved but the admin key was not; retry with PUT and the same setup_alias.

  • 400

    Unknown provider, a handle that is not a slug, malformed config, or a secret that is knowably not this provider's key. code names the common mistakes: platform_key_in_provider_slot (an Experiential xpl_ 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.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 401

    Missing, unknown or revoked API key.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 402

    A Free organization's first paid provider connection needs Pro.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

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

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    The resource does not exist or belongs to another organization.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 409

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

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    The body or query failed validation.

    レスポンス
    • detailarray<object>必須
      detail
      • typestring
      • locarray<string | integer>
      • msgstring

リクエスト

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

レスポンス

{
  "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