POST/api/orgs/{org_id}/provider-connections/{provider}/check

Check a provider account

Probes the stored credential at the provider and persists the verdict. A stored admin key is probed in the same pass and reported under status_detail.spend_key. Plan accounts are refused with 409 (use their refresh-usage action). No request body.

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"

Query parameters

  • setup_aliasstring

    The account handle. Omitted, the provider-named default account.

Responses

  • 200

    The persisted verdict.

    Response
    • 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
  • 400

    The request is malformed or names an unsupported value.

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

  • 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

    The account is a plan account, not an 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).

Request

curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai/check?setup_alias=openai-main \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "provider": "openai",
  "status": "invalid",
  "status_detail": {
    "http_status": 401,
    "provider_code": "invalid_api_key",
    "provider_message": "Incorrect API key provided.",
    "remediation": "Create a new key at platform.openai.com/api-keys and rotate this account."
  },
  "status_checked_at": "2026-11-19T14:10:03.551Z",
  "status_source": "hookup_check"
}

https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai/check?setup_alias=openai-main