A connection represents the relationship between WorkOS and any collection of application users. This collection of application users may include personal or enterprise identity providers. As a layer of abstraction, a WorkOS connection rests between an application and its users, separating an application from the implementation details required by specific standards like OAuth 2.0 and SAML.
See the events reference documentation for the connection events.
Get the details of an existing connection.
cURL
| curl "https://api.workos.com/connections/conn_01E4ZCR3C56J083X43JQXF3JK5" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const connection = await workos.sso.getConnection( | |
| 'conn_01E4ZCR3C56J083X43JQXF3JK5', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.sso.get_connection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.sso.get_connection(id_="conn_01E4ZCR3C56J083X43JQXF3JK5") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.SSO().GetConnection(context.Background(), "conn_01E4ZCR3C56J083X43JQXF3JK5") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->sso()->getConnection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.sso.getConnection("conn_01E4ZCR3C56J083X43JQXF3JK5"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.SSO.GetConnectionAsync("conn_01E4ZCR3C56J083X43JQXF3JK5"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .sso() | |
| .get_connection("conn_01E4ZCR3C56J083X43JQXF3JK5") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "connection", | |
| "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", | |
| "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "connection_type": "OktaSAML", | |
| "name": "Foo Corp", | |
| "state": "active", | |
| "domains": [ | |
| { | |
| "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", | |
| "object": "connection_domain", | |
| "domain": "foo-corp.com" | |
| } | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/connections
Parameters
Returns
Get a list of all of your existing connections matching the criteria specified.
cURL
| curl "https://api.workos.com/connections" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const connectionList = await workos.sso.listConnections(); | |
| console.log(connectionList.data); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.sso.list_connections |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.sso.list_connections() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.SSO().ListConnections(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->sso()->listConnections(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.sso.listConnections(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.SSO.ListConnectionsAsync(); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .sso() | |
| .list_connections() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "connection", | |
| "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", | |
| "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "connection_type": "OktaSAML", | |
| "name": "Foo Corp", | |
| "state": "active", | |
| "domains": [ | |
| { | |
| "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", | |
| "object": "connection_domain", | |
| "domain": "foo-corp.com" | |
| } | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ], | |
| "list_metadata": { | |
| "before": "conn_01HXYZ123456789ABCDEFGHIJ", | |
| "after": "conn_01HXYZ987654321KJIHGFEDCBA" | |
| } | |
| } |
GET/connections
Parameters
Returns object
Creates a new connection for an organization. Provide saml_options or oidc_options to configure the identity provider. When external_id matches an existing connection in the organization, that connection is returned instead of creating a duplicate.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/connections" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Foo Corp", | |
| "external_id": "acme-legacy-conn-42", | |
| "connection_type": "OktaSAML", | |
| "saml_options": { | |
| "idp_metadata_url": "https://idp.example.com/metadata.xml" | |
| } | |
| } | |
| BODY |
| { | |
| "object": "connection", | |
| "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", | |
| "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "connection_type": "OktaSAML", | |
| "name": "Foo Corp", | |
| "state": "active", | |
| "domains": [ | |
| { | |
| "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", | |
| "object": "connection_domain", | |
| "domain": "foo-corp.com" | |
| } | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
POST/connections
Common
Protocol options · provide one
Saml
Oidc
Returns
Updates an existing connection. Only the provided fields are changed; fields that accept null are reset to their default behavior.
cURL
| curl --request PATCH \ | |
| --url "https://api.workos.com/connections/conn_01E4ZCR3C56J083X43JQXF3JK5" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "Foo Corp", | |
| "external_id": "acme-legacy-conn-42", | |
| "saml_options": { | |
| "idp_metadata_url": "https://idp.example.com/metadata.xml" | |
| }, | |
| "attribute_maps": { | |
| "custom_attributes": { | |
| "company": "company_claim" | |
| } | |
| } | |
| } | |
| BODY |
| { | |
| "object": "connection", | |
| "id": "conn_01E4ZCR3C56J083X43JQXF3JK5", | |
| "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "connection_type": "OktaSAML", | |
| "name": "Foo Corp", | |
| "state": "active", | |
| "domains": [ | |
| { | |
| "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A", | |
| "object": "connection_domain", | |
| "domain": "foo-corp.com" | |
| } | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
PATCH/connections
Common
Protocol options · optional, provide one
Saml
Oidc