Test Stored Connection
POST/api/storefront/instances/:id/test-connection
Verify the credentials already stored on the instance and remember what the store reported — the store name and counts are written back onto the instance so the dashboard can name it, and any standing connection error is cleared on success. Takes no body.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Which call is made depends on how the instance was connected (auth on the instance resource):
oauth— the store's owner approved and the store issued the key. Verified throughGET /connect, which proves the key is live AND that the store still has a record of this tenant. The store's record of the connection rides back indata.raw.connection;storeName,versionandcountsare carried over from the last successful health probe.api_key— a key pasted in by hand. Verified throughGET /health, anddata.rawcarries the store's whole health body.
422 with data.ok = false when the store refuses (data.status is the store's HTTP status, e.g. 401) or cannot be reached (data.status is null).
Permission: integrations.sync.
Authentication: Bearer token (session or PAT).
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.