POST/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_idstringrequired

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

  • providerenumrequired

    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"

Request body

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

    One of

    object

    • token_idstringrequired
    • token_secretstringrequired
  • configobject

    Provider config: required for azure_openai, bedrock, vertex and fireworks; ignored (stored empty) for key-only providers.

    Default: {}
    One of

    object

    • endpointstringrequired

      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

    • regionstringrequired
    • auth_modeenum
      "access_key_pair""api_key"
      Default: "access_key_pair"
    • access_key_idstring | null

    object

    • project_idstringrequired
    • regionstringrequired

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

    object

    • account_idstringrequired
  • spend_secretstring | null

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

  • setup_aliasstringrequired

    A new, unique account handle for this provider.

Responses

  • 200

    The saved account and the hookup check's verdict.

    Response
    • connectionobjectrequired

      One connected account. Never carries ids or secrets.

      connection
      • providerenumrequired

        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_aliasstringrequired

        Account handle; the default account's handle is the provider name.

      • configobjectrequired

        Non-secret provider config.

      • credential_last4string | nullrequired
      • spend_credential_last4string | nullrequired

        Last four of the stored admin key, if any.

      • statusenumrequired

        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"
      • priorityintegerrequired

        Position in the org's account pool; lower is tried first.

      • exhaustion_fallbackbooleanrequired

        Whether the pool rotates past this account when it is quota_exhausted.

      • ratelimit_failoverbooleanrequired

        Whether the pool rotates past this account while it is rate limited.

      • failover_only_onarray | nullrequired

        Null for unrestricted; a list makes the account a fallback for exactly those failures.

    • checkobjectrequired

      The persisted verdict of one hookup check.

      check
      • providerenumrequired

        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"
      • statusenumrequired

        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 | nullrequired

        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 | nullrequired
      • status_sourceenum | nullrequired
    • 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.

    Response
    • errorstringrequired

      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.

    Response
    • errorstringrequired

      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.

    Response
    • errorstringrequired

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

    Response
    • errorstringrequired

      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.

    Response
    • errorstringrequired

      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

    An account with this handle already exists for the provider.

    Response
    • errorstringrequired

      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.

    Response
    • detailarray<object>required
      detail
      • typestring
      • locarray<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