---
title: "Test an unsaved candidate connection (before it's created)."
method: POST
path: "/v1/connections/test"
tags: ["connections"]
---

# Test an unsaved candidate connection (before it's created).

`POST /v1/connections/test`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/connections/test`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Probes a candidate connection — the warehouse `config` plus the raw `secret` the
user just entered — without persisting anything (DVT-147). The engine opens the
warehouse, runs a trivial probe (`SELECT 1`), and discards the credential; the raw
secret travels API→engine the same way it does on credential save (the engine is
the sole place plaintext is used to open a connection), and because there is no
stored ciphertext the credential broker is not involved.

This lets the New-connection wizard catch a wrong account / key / role *before*
committing the row — without it, a wrong-but-saved connection's config can only be
fixed by delete-and-recreate. Admin or above.

A failed probe is a normal `200` result with `ok: false` and a (credential-free)
`error`; `4xx` is reserved for authorization and a malformed request. Secret-shaped
keys are rejected in `config` (the credential belongs in `secret`).

## Request body

- object
  - `type` string, required: Warehouse type (e.g. postgres, snowflake).
  - `authMethod` string, required: Auth method the driver opens the connection with (e.g. service_secret, service_keypair).
  - `config` object: Non-secret connection config. Must not contain secret-shaped keys.
  - `secret` string: The raw credential to test with (password or PEM key). Never persisted or echoed.

## Response `200`

The probe outcome (whether or not the candidate warehouse was reachable).

- object
  - `data` object, required
    - `ok` boolean, required: True when the probe succeeded.
    - `error` string: Failure detail when ok is false; omitted on success.
    - `testedAt` string, date-time, required

## Other responses

- `400`: Malformed request.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `429`: Per-actor API rate limit exceeded (SEC-2). All authenticated `/v1` routes apply a per-actor fixed-window default tier; selected compute-heavy routes (connection tests, column describe, data export) apply an additional tighter tier. Auth endpoints apply a per-IP tier. Problem type: `https://docs.dvt.dev/errors/rate-limited`. Wait for the `Retry-After` response header value (seconds) before retrying.

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)