Create a connection (store credentials for one piece)

Stores a credential set for exactly ONE piece. A connection is not a generic secret store: it belongs to pieceId (e.g. slack, postgres, googlesheets) and a slack connection can never be used by a postgres step.

HOW TO KNOW WHAT GOES IN config: the credential fields are declared by the PIECE, not by this endpoint. Call GET /api/pieces/{pieceId} and read its auth object — auth.required says whether the piece uses a connection at all, auth.type names the shape (none, api_key, bearer_token, basic_auth, oauth2, custom), and auth.fields[] lists {name, title, type, required, description}. Every key you put in config is an auth.fields[].name; a field of type: "password" is a secret. For an OAuth2 piece, auth.oauth2 carries authorizationUrl, tokenUrl and default scopes, so you normally supply only clientId/clientSecret here and then run POST /api/connections/{id}/oauth2/start.

VALIDATION AGAINST THE FLEET: when the live worker fleet has published a catalog, pieceId must be a piece the fleet actually runs AND that piece must declare auth.required: true — otherwise 400 ("Unknown piece" / "This piece does not use a connection"). config itself is NOT validated field-by-field: missing or misspelled credential keys are accepted silently and only surface when the connection is tested or used in a run.

authType is a free-text label recorded on the row; it is NOT checked against the piece and does not change how the credential is used. Omitted, it defaults to "api_key".

STATUS ON CREATE: normally active. The one exception is the generic oauth2 piece with no accessToken in config — that row is created pending, because client credentials alone cannot call anything until the authorization flow has run.

USING IT FROM A WORKFLOW: reference it BY ID. A step or trigger in a workflow definition carries "connectionId": "<this id>" next to its pieceId; credentials are never inlined into a step's config. The connection must be in the same workspace as the workflow.

The response echoes the created row and, like every connection response, contains no credential material.