Set IdP-initiated sign-in for a SAML connection

PUT /v1/connections/{connection_id}/idp-initiated · permission connections:write

Allows or turns off IdP-initiated sign-in (an unsolicited SAML response sent from the identity provider's app portal) for an enterprise SAML connection, and sets the applications the user may land in. It is off by default.

Full replace: every request writes all three fields. An omitted idp_initiated_default_application_id and an empty idp_initiated_allowed_application_ids are cleared.
Targets: each application must exist in this environment, sign users in through a browser (not machine-to-machine, management or a client ID metadata document client) and have an initiate_login_uri. After sign-in the browser is sent to that address with iss, and the application starts its own authorization request with state and PKCE.
RelayState: when the identity provider sends a RelayState, it selects an application only if it equals that application's client_id byte for byte and the application is the default or in the allowed list. RelayState is never treated as a URL.
Security: this setting accepts responses your users did not start, so a dashboard user needs a fresh step-up authentication and the owner or admin role. The Admin Portal cannot change it.

Request

Field	Type	Required	Description
`connection_id`	path	yes	Enterprise SAML connection ID (`conn_…`).
`If-Match`	header	no	The connection `ETag`. A stale value fails with `412`.
`allow_idp_initiated`	boolean	yes	Accept unsolicited SAML responses. `true` requires `idp_initiated_default_application_id`.
`idp_initiated_default_application_id`	string \| null	when enabled	Application (`app_…`) used when the RelayState is empty.
`idp_initiated_allowed_application_ids`	array	no	Applications (`app_…`) a RelayState may select; unique, at most 20.

Response

200 OK with the connection (see Get a connection) and its new ETag. The connection shows the stored values in allow_idp_initiated, idp_initiated_default_application_id and idp_initiated_allowed_application_ids.

Errors

HTTP	code	When
404	`not_found`	The connection does not exist in this environment.
412	`precondition_failed`	`If-Match` does not match the current version.
422	`validation_failed`	The connection is not an enterprise SAML connection, the default application is missing while enabled, or an application does not meet the target rules; `errors[]` points at the field.
400	`unknown_field`	The body has an unknown field.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
403	`step_up_required`	A dashboard user has not completed a recent step-up authentication.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	A dependency is temporarily unavailable; retry after the `Retry-After` period.

Example

curl -X PUT "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/idp-initiated" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_idp_initiated":true,"idp_initiated_default_application_id":"app_01j9xp6q0r1s5t7v9w1x3y5z7c","idp_initiated_allowed_application_ids":["app_01j9xp6q0r1s5t7v9w1x3y5z7c"]}'

keenauth connections idp-initiated put conn_01j9xp6q0r1s5t7v9w1x3y5z7b --data '{"allow_idp_initiated":false}'