Check a collector connection

GET /v1/collector/connection validates a Connection key, ingest token and request signature. It returns the Integration and environment bound to those credentials. It does not record an observation, enqueue analysis, or verify your application.

Endpoint

Code example

GET https://api.seamward.com/v1/collector/connection

There are no body, path or query parameters. Supply X-Seamward-Connection, Authorization: Bearer <ingest token> and X-Seamward-Signature. Follow request signing, using an empty body: the signed text is the timestamp followed by a period. Never send CLI login tokens.

For local setup, use the interactive CLI instead of handling secrets manually:

Code example

seamward setup verify

For direct API use, load your credentials privately into the two environment variables used below. This Node.js example avoids placing secrets in process arguments or printing them:

Code example

import { createHmac } from "node:crypto";
const token = process.env.SEAMWARD_INGEST_TOKEN;const key = process.env.SEAMWARD_CONNECTION_KEY;if (!token || !key) throw new Error("Load collector credentials first");const timestamp = Math.floor(Date.now() / 1000);const signature = createHmac("sha256", token)  .update(`${timestamp}.`)  .digest("hex");const response = await fetch(  "https://api.seamward.com/v1/collector/connection",  {    redirect: "error",    signal: AbortSignal.timeout(15000),    headers: {      Authorization: `Bearer ${token}`,      "X-Seamward-Connection": key,      "X-Seamward-Signature": `t=${timestamp},v1=${signature}`,    },  },);if (!response.ok)  throw new Error(`Connection check failed (${response.status})`);console.log(await response.json());

Response

HTTP 200, with Cache-Control: no-store:

Code example

{  "status": "connection_verified",  "integrationId": "int_example",  "environmentId": "env_development",  "applicationVerified": false}

All four fields are required. status is always connection_verified; integrationId and environmentId identify the authenticated scope; applicationVerified is always false. Compare the IDs to your expected Integration and environment before reporting success. This response is a check at request time, not a durable health status or proof that your app loads its file.

Errors

Status	Error	Action
401	`unauthenticated`	Check the key/token pair, token revocation, signature and clock. Signature failures can include a `reason`; see authentication.
429	`connection_rate_limited`	Wait for the `Retry-After` seconds before retrying. The API allows 120 checks per client IP per minute per process and limits tracked IPs to 10,000.

Network failure is not a credential verdict. Retry after connectivity recovers. An older deployment returning 404 does not support this endpoint; update the service before using connection verification. No check creates application traffic. Continue with local setup and confirm real observations after starting your application.