---
title: "Validate Source Connection"
method: POST
path: "/sources/connectors/{code}/validate"
tags: ["Sources"]
---

# Validate Source Connection

`POST /sources/connectors/{code}/validate`

## Request

- Base URL: `https://api.streamkap.com`
- URL: `https://api.streamkap.com/sources/connectors/{code}/validate`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/streamkap/apis/streamkap-rest-api/docs/sources/connectors/:code/validate/post.ts> (a function with typed inputs; its response is checked against the schema)

Pre-save connection test for an API-source connector (the form's "Test connection" button).

Runs the vendor's credential probe plus per-resource access checks against the SUBMITTED config —
nothing is persisted; the secret travels in the request body only. **200 always carries the
structured result** (a failed test is a result, not an HTTP error): `credential_ok` + `message`
(+ `field`, the config field a rejected credential is fixed on) for the token, per-resource
`ok`/`message` for scope gaps (+ `needs`, what the resource lacks, and `fix`, a remedy shared verbatim by
every resource it fixes, when the refusal is a missing permission, scope or product), `account_in_use`
(+ the clashing source's `existing_source_id`) when the vendor account already backs another source in
this workspace (the save would 409). HTTP errors
mean the test could not run: 404 unknown connector, 400 unsupported vendor / masked secret without
`source_id` / malformed config, 403 without `source_id` when the connector is not available on this
deployment (the contract's `unavailable_reason`), 502 vendor outage. The schema contract's
`capabilities` field declares whether a connector supports this at all.
On the edit form, pass `source_id` so a masked secret resolves to the stored credential.

## Path parameters

- `code` string, required

## Request body

- ValidateConnectionRequest: Body of ``POST /sources/connectors/{code}/validate`` — the submitted (unsaved) config to test. ``source_id`` is set by the edit form so a masked secret resolves to the stored credential; absent on the create form (a masked secret without it is a 400).
  - `config` object, required
  - `source_id` string, nullable: On an edit, the source whose stored secrets masked values in `config` resolve to. Omit on create; a masked secret without it is a 400.

## Response `200`

Successful Response

- ConnectionValidation: Result of a pre-save connection test (``POST /sources/connectors/{code}/validate``). Always returned with HTTP 200 when the test RAN — a failed test is a successful validation run, not an HTTP error. ``valid`` is the roll-up: credentials accepted AND every checked resource accessible. ``account_in_use`` is a tenant-scoped warning (a create would 409), deliberately not folded into ``valid`` — the connection itself works.
  - `valid` boolean, required
  - `credential_ok` boolean, required
  - `message` string, nullable
  - `field` string, nullable
  - `account_id` string, nullable
  - `account_in_use` boolean
  - `existing_source_id` string, nullable
  - `resources` ResourceAccess[]
    - `name` string, required: The resource, as named in the config's `resources`.
    - `ok` boolean, required: Whether the credentials can read this resource.
    - `message` string, nullable: Why the resource failed, or was not checked.
    - `warning` string, nullable: Advice on a resource that passed but may sync nothing useful as configured.
    - `needs` string, nullable: The permission, scope or product the resource lacks, as the vendor names it.
    - `fix` string, nullable: How to grant what `needs` names; identical for every resource with the same fix.
    - `checked` boolean: False when the test did not read this resource; a save warns about it instead of refusing.

## Other responses

- `403`: The API connector is not available on this deployment: no sign-in mode is configured for it.
- `422`: Validation Error

## Changes

- **2026-10-01** `50e54c2e65f2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/streamkap/apis/streamkap-rest-api/changes/sources/connectors/:code/validate/post.md)

---

[API](https://skmtc.dev/streamkap/apis/streamkap-rest-api.md) - [All operations](https://skmtc.dev/streamkap/apis/streamkap-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/streamkap/apis/streamkap-rest-api/revisions/56dda39bb53c?raw)