# SSO Clients
## List SSO clients
> Returns the list of SSO clients configured on the account.\
> \
> Each Celigo account may have \*\*at most one\*\* SSO client. If no SSO client has been\
> created yet the API returns \`204 No Content\` with an empty body.\
> \
> AI guidance:\
> \- Expect either a single-element array (200) or an empty response (204).\
> \- The \`oidc.clientSecret\` field is always masked as \`"\*\*\*\*\*\*"\`.\
> \- Use \`GET /v1/ssoclients/{\_id}\` if you already have the client ID.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Complete SSO client object as returned by the API.\n\nIncludes all user-supplied fields from the request plus server-generated metadata\n(`_id`, `createdAt`, `lastModified`). The `oidc.clientSecret` field is always masked\nas `\"******\"` in responses.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the SSO client resource."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the SSO client was created."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification to the SSO client."}}}]},"Request":{"type":"object","description":"Fields that can be sent when creating or updating an SSO client configuration.\n\nAn SSO client enables Single Sign-On for the Celigo account using an external identity\nprovider (IdP). Currently only OpenID Connect (OIDC) is supported. Each account may have\nat most one SSO client.\n\nAI guidance:\n- `type` must be `\"oidc\"` (the only supported type today).\n- `orgId` is the organisation slug users will see in the SSO login URL. It must be 3-20\n alphanumeric characters and start with a letter.\n- The nested `oidc` object carries the IdP connection details. `clientSecret` is stored\n encrypted and always returned masked (`\"******\"`) in GET responses.\n","required":["type","orgId","oidc"],"properties":{"type":{"type":"string","description":"SSO protocol type. Currently only `\"oidc\"` (OpenID Connect) is supported.\n\nAI guidance: always set this to `\"oidc\"`.\n","enum":["oidc"]},"disabled":{"type":"boolean","description":"Controls whether SSO login is active for the account.\n\nWhen `true`, users cannot authenticate via the SSO client and must use standard\nCeligo credentials instead. Set to `false` (the default) to enforce SSO.\n","default":false},"orgId":{"type":"string","description":"Organisation identifier that appears in the SSO login URL\n(e.g., `https://integrator.io/sso/`).\n\nConstraints:\n- 3 to 20 characters\n- Alphanumeric only (`[A-Za-z0-9]`)\n- Must start with a letter\n\nAI guidance: choose a short, memorable slug that matches the company name\n(e.g., `\"acmecorp\"`).\n","pattern":"^[A-Za-z][A-Za-z0-9]{2,19}$","minLength":3,"maxLength":20},"oidc":{"type":"object","description":"OpenID Connect configuration for the SSO client. Required when `type` is `\"oidc\"`.\n\nAI guidance:\n- `issuerURL` is the base URL of the IdP's OIDC discovery endpoint (e.g.,\n `https://accounts.google.com` or `https://login.microsoftonline.com/{tenant}/v2.0`).\n- `clientId` and `clientSecret` are obtained from the IdP when registering Celigo\n as an OAuth 2.0 / OIDC application.\n","required":["issuerURL","clientId","clientSecret"],"properties":{"issuerURL":{"type":"string","format":"uri","description":"The OIDC issuer URL of the identity provider. This must match the `iss` claim\nin the ID tokens issued by the IdP.\n\nThe Celigo platform uses this URL to discover the IdP's authorization, token,\nuserinfo, and JWKS endpoints via the `.well-known/openid-configuration` document.\n"},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the identity provider for the\nCeligo application.\n"},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret registered with the identity provider.\n\nThis value is stored encrypted on the Celigo side and is always returned\nmasked as `\"******\"` in GET responses.\n"}}}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/ssoclients":{"get":{"summary":"List SSO clients","description":"Returns the list of SSO clients configured on the account.\n\nEach Celigo account may have **at most one** SSO client. If no SSO client has been\ncreated yet the API returns `204 No Content` with an empty body.\n\nAI guidance:\n- Expect either a single-element array (200) or an empty response (204).\n- The `oidc.clientSecret` field is always masked as `\"******\"`.\n- Use `GET /v1/ssoclients/{_id}` if you already have the client ID.\n","operationId":"listSSOClients","tags":["SSO Clients"],"responses":{"200":{"description":"Successfully retrieved SSO client list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"204":{"description":"No SSO clients exist in the account"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```
## Create an SSO client
> Creates a new SSO client for the account.\
> \
> Only one SSO client is allowed per account. Attempting to create a second client\
> returns \`422\` with error code \`not\_allowed\`.\
> \
> AI guidance:\
> \- Set \`type\` to \`"oidc"\` (the only supported value).\
> \- \`orgId\` must be 3-20 alphanumeric characters starting with a letter. This becomes\
> the slug in the SSO login URL.\
> \- Provide the IdP connection details in \`oidc.issuerURL\`, \`oidc.clientId\`, and\
> \`oidc.clientSecret\`.\
> \- On success the response includes the server-generated \`\_id\`, \`createdAt\`, and\
> \`lastModified\` fields.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Fields that can be sent when creating or updating an SSO client configuration.\n\nAn SSO client enables Single Sign-On for the Celigo account using an external identity\nprovider (IdP). Currently only OpenID Connect (OIDC) is supported. Each account may have\nat most one SSO client.\n\nAI guidance:\n- `type` must be `\"oidc\"` (the only supported type today).\n- `orgId` is the organisation slug users will see in the SSO login URL. It must be 3-20\n alphanumeric characters and start with a letter.\n- The nested `oidc` object carries the IdP connection details. `clientSecret` is stored\n encrypted and always returned masked (`\"******\"`) in GET responses.\n","required":["type","orgId","oidc"],"properties":{"type":{"type":"string","description":"SSO protocol type. Currently only `\"oidc\"` (OpenID Connect) is supported.\n\nAI guidance: always set this to `\"oidc\"`.\n","enum":["oidc"]},"disabled":{"type":"boolean","description":"Controls whether SSO login is active for the account.\n\nWhen `true`, users cannot authenticate via the SSO client and must use standard\nCeligo credentials instead. Set to `false` (the default) to enforce SSO.\n","default":false},"orgId":{"type":"string","description":"Organisation identifier that appears in the SSO login URL\n(e.g., `https://integrator.io/sso/`).\n\nConstraints:\n- 3 to 20 characters\n- Alphanumeric only (`[A-Za-z0-9]`)\n- Must start with a letter\n\nAI guidance: choose a short, memorable slug that matches the company name\n(e.g., `\"acmecorp\"`).\n","pattern":"^[A-Za-z][A-Za-z0-9]{2,19}$","minLength":3,"maxLength":20},"oidc":{"type":"object","description":"OpenID Connect configuration for the SSO client. Required when `type` is `\"oidc\"`.\n\nAI guidance:\n- `issuerURL` is the base URL of the IdP's OIDC discovery endpoint (e.g.,\n `https://accounts.google.com` or `https://login.microsoftonline.com/{tenant}/v2.0`).\n- `clientId` and `clientSecret` are obtained from the IdP when registering Celigo\n as an OAuth 2.0 / OIDC application.\n","required":["issuerURL","clientId","clientSecret"],"properties":{"issuerURL":{"type":"string","format":"uri","description":"The OIDC issuer URL of the identity provider. This must match the `iss` claim\nin the ID tokens issued by the IdP.\n\nThe Celigo platform uses this URL to discover the IdP's authorization, token,\nuserinfo, and JWKS endpoints via the `.well-known/openid-configuration` document.\n"},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the identity provider for the\nCeligo application.\n"},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret registered with the identity provider.\n\nThis value is stored encrypted on the Celigo side and is always returned\nmasked as `\"******\"` in GET responses.\n"}}}}},"Response":{"type":"object","description":"Complete SSO client object as returned by the API.\n\nIncludes all user-supplied fields from the request plus server-generated metadata\n(`_id`, `createdAt`, `lastModified`). The `oidc.clientSecret` field is always masked\nas `\"******\"` in responses.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the SSO client resource."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the SSO client was created."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification to the SSO client."}}}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/ssoclients":{"post":{"summary":"Create an SSO client","description":"Creates a new SSO client for the account.\n\nOnly one SSO client is allowed per account. Attempting to create a second client\nreturns `422` with error code `not_allowed`.\n\nAI guidance:\n- Set `type` to `\"oidc\"` (the only supported value).\n- `orgId` must be 3-20 alphanumeric characters starting with a letter. This becomes\n the slug in the SSO login URL.\n- Provide the IdP connection details in `oidc.issuerURL`, `oidc.clientId`, and\n `oidc.clientSecret`.\n- On success the response includes the server-generated `_id`, `createdAt`, and\n `lastModified` fields.\n","operationId":"createSSOClient","tags":["SSO Clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"SSO client created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```
## Get an SSO client
> Returns the complete configuration of a specific SSO client.\
> \
> AI guidance:\
> \- The \`oidc.clientSecret\` field is always masked as \`"\*\*\*\*\*\*"\` in the response.\
> \- Use this endpoint to verify SSO configuration or check the \`disabled\` flag.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Complete SSO client object as returned by the API.\n\nIncludes all user-supplied fields from the request plus server-generated metadata\n(`_id`, `createdAt`, `lastModified`). The `oidc.clientSecret` field is always masked\nas `\"******\"` in responses.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the SSO client resource."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the SSO client was created."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification to the SSO client."}}}]},"Request":{"type":"object","description":"Fields that can be sent when creating or updating an SSO client configuration.\n\nAn SSO client enables Single Sign-On for the Celigo account using an external identity\nprovider (IdP). Currently only OpenID Connect (OIDC) is supported. Each account may have\nat most one SSO client.\n\nAI guidance:\n- `type` must be `\"oidc\"` (the only supported type today).\n- `orgId` is the organisation slug users will see in the SSO login URL. It must be 3-20\n alphanumeric characters and start with a letter.\n- The nested `oidc` object carries the IdP connection details. `clientSecret` is stored\n encrypted and always returned masked (`\"******\"`) in GET responses.\n","required":["type","orgId","oidc"],"properties":{"type":{"type":"string","description":"SSO protocol type. Currently only `\"oidc\"` (OpenID Connect) is supported.\n\nAI guidance: always set this to `\"oidc\"`.\n","enum":["oidc"]},"disabled":{"type":"boolean","description":"Controls whether SSO login is active for the account.\n\nWhen `true`, users cannot authenticate via the SSO client and must use standard\nCeligo credentials instead. Set to `false` (the default) to enforce SSO.\n","default":false},"orgId":{"type":"string","description":"Organisation identifier that appears in the SSO login URL\n(e.g., `https://integrator.io/sso/`).\n\nConstraints:\n- 3 to 20 characters\n- Alphanumeric only (`[A-Za-z0-9]`)\n- Must start with a letter\n\nAI guidance: choose a short, memorable slug that matches the company name\n(e.g., `\"acmecorp\"`).\n","pattern":"^[A-Za-z][A-Za-z0-9]{2,19}$","minLength":3,"maxLength":20},"oidc":{"type":"object","description":"OpenID Connect configuration for the SSO client. Required when `type` is `\"oidc\"`.\n\nAI guidance:\n- `issuerURL` is the base URL of the IdP's OIDC discovery endpoint (e.g.,\n `https://accounts.google.com` or `https://login.microsoftonline.com/{tenant}/v2.0`).\n- `clientId` and `clientSecret` are obtained from the IdP when registering Celigo\n as an OAuth 2.0 / OIDC application.\n","required":["issuerURL","clientId","clientSecret"],"properties":{"issuerURL":{"type":"string","format":"uri","description":"The OIDC issuer URL of the identity provider. This must match the `iss` claim\nin the ID tokens issued by the IdP.\n\nThe Celigo platform uses this URL to discover the IdP's authorization, token,\nuserinfo, and JWKS endpoints via the `.well-known/openid-configuration` document.\n"},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the identity provider for the\nCeligo application.\n"},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret registered with the identity provider.\n\nThis value is stored encrypted on the Celigo side and is always returned\nmasked as `\"******\"` in GET responses.\n"}}}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/ssoclients/{_id}":{"get":{"summary":"Get an SSO client","description":"Returns the complete configuration of a specific SSO client.\n\nAI guidance:\n- The `oidc.clientSecret` field is always masked as `\"******\"` in the response.\n- Use this endpoint to verify SSO configuration or check the `disabled` flag.\n","operationId":"getSSOClientById","tags":["SSO Clients"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the SSO client","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"SSO client retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## Update an SSO client
> Replaces an existing SSO client with the provided configuration.\
> \
> This is a full-body replacement: every field you want to keep must be included\
> in the request body. Omitted fields revert to their defaults or are removed.\
> \
> AI guidance:\
> \- Always GET the current SSO client first, merge your changes, then PUT the full body.\
> \- The same validation rules as POST apply (e.g., \`orgId\` pattern, required \`oidc\` fields).\
> \- On success the response contains the updated SSO client with a new \`lastModified\` timestamp.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Fields that can be sent when creating or updating an SSO client configuration.\n\nAn SSO client enables Single Sign-On for the Celigo account using an external identity\nprovider (IdP). Currently only OpenID Connect (OIDC) is supported. Each account may have\nat most one SSO client.\n\nAI guidance:\n- `type` must be `\"oidc\"` (the only supported type today).\n- `orgId` is the organisation slug users will see in the SSO login URL. It must be 3-20\n alphanumeric characters and start with a letter.\n- The nested `oidc` object carries the IdP connection details. `clientSecret` is stored\n encrypted and always returned masked (`\"******\"`) in GET responses.\n","required":["type","orgId","oidc"],"properties":{"type":{"type":"string","description":"SSO protocol type. Currently only `\"oidc\"` (OpenID Connect) is supported.\n\nAI guidance: always set this to `\"oidc\"`.\n","enum":["oidc"]},"disabled":{"type":"boolean","description":"Controls whether SSO login is active for the account.\n\nWhen `true`, users cannot authenticate via the SSO client and must use standard\nCeligo credentials instead. Set to `false` (the default) to enforce SSO.\n","default":false},"orgId":{"type":"string","description":"Organisation identifier that appears in the SSO login URL\n(e.g., `https://integrator.io/sso/`).\n\nConstraints:\n- 3 to 20 characters\n- Alphanumeric only (`[A-Za-z0-9]`)\n- Must start with a letter\n\nAI guidance: choose a short, memorable slug that matches the company name\n(e.g., `\"acmecorp\"`).\n","pattern":"^[A-Za-z][A-Za-z0-9]{2,19}$","minLength":3,"maxLength":20},"oidc":{"type":"object","description":"OpenID Connect configuration for the SSO client. Required when `type` is `\"oidc\"`.\n\nAI guidance:\n- `issuerURL` is the base URL of the IdP's OIDC discovery endpoint (e.g.,\n `https://accounts.google.com` or `https://login.microsoftonline.com/{tenant}/v2.0`).\n- `clientId` and `clientSecret` are obtained from the IdP when registering Celigo\n as an OAuth 2.0 / OIDC application.\n","required":["issuerURL","clientId","clientSecret"],"properties":{"issuerURL":{"type":"string","format":"uri","description":"The OIDC issuer URL of the identity provider. This must match the `iss` claim\nin the ID tokens issued by the IdP.\n\nThe Celigo platform uses this URL to discover the IdP's authorization, token,\nuserinfo, and JWKS endpoints via the `.well-known/openid-configuration` document.\n"},"clientId":{"type":"string","description":"OAuth 2.0 client identifier registered with the identity provider for the\nCeligo application.\n"},"clientSecret":{"type":"string","description":"OAuth 2.0 client secret registered with the identity provider.\n\nThis value is stored encrypted on the Celigo side and is always returned\nmasked as `\"******\"` in GET responses.\n"}}}}},"Response":{"type":"object","description":"Complete SSO client object as returned by the API.\n\nIncludes all user-supplied fields from the request plus server-generated metadata\n(`_id`, `createdAt`, `lastModified`). The `oidc.clientSecret` field is always masked\nas `\"******\"` in responses.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the SSO client resource."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the SSO client was created."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification to the SSO client."}}}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/ssoclients/{_id}":{"put":{"summary":"Update an SSO client","description":"Replaces an existing SSO client with the provided configuration.\n\nThis is a full-body replacement: every field you want to keep must be included\nin the request body. Omitted fields revert to their defaults or are removed.\n\nAI guidance:\n- Always GET the current SSO client first, merge your changes, then PUT the full body.\n- The same validation rules as POST apply (e.g., `orgId` pattern, required `oidc` fields).\n- On success the response contains the updated SSO client with a new `lastModified` timestamp.\n","operationId":"updateSSOClient","tags":["SSO Clients"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the SSO client","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"SSO client updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```
## Delete an SSO client
> Deletes an SSO client from the account.\
> \
> After deletion, users can no longer authenticate via SSO and must use standard\
> Celigo credentials. A new SSO client can be created afterwards.\
> \
> AI guidance:\
> \- Returns \`204\` on success with no body.\
> \- Returns \`404\` with error code \`invalid\_ref\` and message \`"SSOClient not found."\` if\
> the \`\_id\` does not match an existing SSO client.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/ssoclients/{_id}":{"delete":{"summary":"Delete an SSO client","description":"Deletes an SSO client from the account.\n\nAfter deletion, users can no longer authenticate via SSO and must use standard\nCeligo credentials. A new SSO client can be created afterwards.\n\nAI guidance:\n- Returns `204` on success with no body.\n- Returns `404` with error code `invalid_ref` and message `\"SSOClient not found.\"` if\n the `_id` does not match an existing SSO client.\n","operationId":"deleteSSOClient","tags":["SSO Clients"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the SSO client","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"SSO client deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## Get audit log for a specific SSO client
> Retrieves the audit log for a specific SSO client, showing the history of changes\
> and actions performed on it.\
> \
> Each entry includes the event type, timestamp, acting user, and a list of\
> field-level changes.\
> \
> AI guidance:\
> \- The \`\_limit\` and \`\_offset\` query parameters are accepted but currently \*\*ignored\*\*\
> by the server -- all matching entries are returned in a single response.\
> \- Entries are returned newest-first.\
> \- \`fieldChanges\[].oldValue\` is absent on \`create\` events; \`fieldChanges\[].newValue\`\
> is absent on \`delete\` events.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SSOClientAuditEntry":{"type":"object","description":"An audit log entry for an SSO client resource.\n\nEach entry records a single change event (create, update, delete) along with\nthe user who performed the action and the specific fields that changed.\n\nAI guidance:\n- `fieldChanges` contains one item per changed field; `oldValue` is absent on create\n events and `newValue` is absent on delete events.\n- `source` indicates how the change was triggered (`\"ui\"`, `\"api\"`, `\"system\"`, etc.).\n- The `_limit` / `_offset` query parameters on the audit endpoint are accepted but\n currently ignored by the server.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for this audit entry."},"resourceType":{"type":"string","readOnly":true,"description":"Always `\"ssoclient\"` for SSO client audit entries.","enum":["ssoclient"]},"_resourceId":{"type":"string","format":"objectId","readOnly":true,"description":"The `_id` of the SSO client this audit entry belongs to."},"source":{"type":"string","readOnly":true,"description":"Where the change originated.\n"},"fieldChanges":{"type":"array","readOnly":true,"description":"List of field-level changes recorded in this event.","items":{"type":"object","properties":{"fieldPath":{"type":"string","description":"Dot-path to the changed field (e.g., `oidc.issuerURL`)."},"oldValue":{"description":"Previous value (may be any JSON type). Absent on create events."},"newValue":{"description":"New value (may be any JSON type). Absent on delete events."}}}},"event":{"type":"string","readOnly":true,"description":"The type of change that was recorded.","enum":["create","update","delete"]},"time":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the action occurred."},"byUser":{"type":"object","readOnly":true,"description":"The user who performed the action.","properties":{"_id":{"type":"string","format":"objectId","description":"User ID."},"email":{"type":"string","format":"email","description":"User email address."},"name":{"type":"string","description":"User display name."}}}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/ssoclients/{_id}/audit":{"get":{"summary":"Get audit log for a specific SSO client","description":"Retrieves the audit log for a specific SSO client, showing the history of changes\nand actions performed on it.\n\nEach entry includes the event type, timestamp, acting user, and a list of\nfield-level changes.\n\nAI guidance:\n- The `_limit` and `_offset` query parameters are accepted but currently **ignored**\n by the server -- all matching entries are returned in a single response.\n- Entries are returned newest-first.\n- `fieldChanges[].oldValue` is absent on `create` events; `fieldChanges[].newValue`\n is absent on `delete` events.\n","operationId":"getSSOClientAudit","tags":["SSO Clients"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the SSO client","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Successfully retrieved audit log","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SSOClientAuditEntry"}}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```
## Get signed URL to download SSO client audit logs
> Generates a pre-signed URL for downloading a CSV export of audit logs for the\
> specified SSO client resources.\
> \
> AI guidance:\
> \- The request body requires \`\_resourceIds\`, an array of SSO client \`\_id\` values.\
> \- The response includes \`signedURL\` (the download link) and \`hasMore\` (whether\
> additional batches exist).\
> \- \*\*Important:\*\* the API path uses the \*\*plural\*\* form \`/ssoclients/audit/signedURL\`.\
> Using the singular \`/ssoclient/audit/signedURL\` returns an \`audit\_not\_supported\` error.
```json
{"openapi":"3.1.0","info":{"title":"SSO Clients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AuditSignedUrlResponse":{"type":"object","description":"Response from `POST /v1/ssoclients/audit/signedURL`.\n\nContains a pre-signed URL for downloading an audit-log CSV export covering the\nrequested SSO client resources.\n\nAI guidance:\n- If `hasMore` is `true`, additional pages of audit data exist beyond the current\n CSV download. Repeat the request to retrieve subsequent batches.\n","properties":{"signedURL":{"type":"string","format":"uri","description":"Pre-signed URL to download the audit CSV. Expires after a short TTL."},"hasMore":{"type":"boolean","description":"Whether additional batches of audit data are available beyond this download."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/ssoclients/audit/signedURL":{"post":{"summary":"Get signed URL to download SSO client audit logs","description":"Generates a pre-signed URL for downloading a CSV export of audit logs for the\nspecified SSO client resources.\n\nAI guidance:\n- The request body requires `_resourceIds`, an array of SSO client `_id` values.\n- The response includes `signedURL` (the download link) and `hasMore` (whether\n additional batches exist).\n- **Important:** the API path uses the **plural** form `/ssoclients/audit/signedURL`.\n Using the singular `/ssoclient/audit/signedURL` returns an `audit_not_supported` error.\n","operationId":"getSSOClientAuditSignedUrl","tags":["SSO Clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body specifying which SSO client resources to include in the\naudit CSV export.\n","required":["_resourceIds"],"properties":{"_resourceIds":{"type":"array","description":"List of SSO client `_id` values to include in the export.","items":{"type":"string","format":"objectId"}}}}}}},"responses":{"200":{"description":"Signed URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditSignedUrlResponse"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.celigo.com/api/api-reference/sso-clients.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.