--- title: "Start Source Oauth" method: POST path: "/sources/connectors/{code}/oauth/start" tags: ["Sources"] --- # Start Source Oauth `POST /sources/connectors/{code}/oauth/start` ## Request - Base URL: `https://api.streamkap.com` - URL: `https://api.streamkap.com/sources/connectors/{code}/oauth/start` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Begin the platform OAuth install flow: return the provider authorize URL for the client to open. The ``state`` minted here is bound to the calling tenant and user. The response carries the ``authorize_url`` (open it in a popup) and the ``state``: poll ``/oauth/grant`` with the state to collect the outcome, which keeps working when a provider's Cross-Origin-Opener-Policy severs the popup's opener (the callback ``postMessage`` is only a best-effort fast path). The optional ``environment`` in the body picks WHICH of the connector's authorization environments to use — for Salesforce, ``production`` (the default) or ``sandbox``, whose orgs cannot authenticate at the production login host at all. The schema contract's ``oauth.environments`` lists the valid keys. It is a key into that fixed set, never a host: an unknown one is a 400. 404 for a connector that declares no OAuth descriptor (``capabilities.oauth_connect`` is false); 400 for an unknown environment, or if the platform app/base URL is not provisioned for this environment. No secret is issued to the browser. A 400 that concerns one form field (a per-account host the start refused, such as a Zendesk subdomain with no live account) also carries ``fields: [{"field", "message"}]`` beside the string ``detail``, the shape a refused create uses. A connector whose flow runs as the customer's own OAuth client (the contract's ``oauth.client_fields``) takes that client's ``client_id`` and ``client_secret`` in the body; on edit, omit the secret (or send the mask) with ``source_id`` to keep the source's stored secret. ## Path parameters - `code` string, required ## Request body - OAuthStartRequest: Body of ``POST /sources/connectors/{code}/oauth/start``. ``environment`` names WHICH of the vendor's declared authorization environments to authorize against (for Salesforce, ``production`` or ``sandbox``). It is a KEY into a fixed, vendor-declared set — never a host or URL, which would make the token endpoint a caller-chosen request target. Omitting it takes the vendor's default; an unknown key is rejected, not defaulted. For a vendor whose host is the customer's own account (``OAuthDescriptor.host_field``, Zendesk's subdomain) it carries that account, which the vendor's allowlist validates before any URL is built from it. - `environment` string, nullable: A key from the contract's `oauth.environments`, e.g. `production` (the default) or `sandbox`; an unknown key is a 400. For a connector with `oauth.host_field` (Zendesk), that field's value: the subdomain. - `client_id` string, nullable: The customer's own OAuth client ID, for a connector whose contract lists `oauth.client_fields`. - `client_secret` string, password, nullable: The customer's own OAuth client secret, for a connector whose contract lists `oauth.client_fields`. On edit, omit it (or send the mask) with `source_id` to keep the stored secret. - `source_id` string, nullable: On edit, the source whose stored client secret is kept when `client_secret` is omitted or masked. ## Response `200` Successful Response - object ## Other responses - `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/oauth/start/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)