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 "https://api.workos.com/connections/conn_01E4ZCR3C56J083X43JQXF3JK5" \ --header "Authorization: Bearer sk_example_123456789"
{ "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" } ], "options": { "signing_cert": null }, "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| 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.key = "sk_example_123456789" | |
| end | |
| connection = WorkOS::SSO.get_connection( | |
| id: "conn_01E4ZCR3C56J083X43JQXF3JK5" | |
| ) |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| connection = workos_client.sso.get_connection( | |
| connection_id="conn_01E4ZCR3C56J083X43JQXF3JK5" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v3/pkg/sso" | |
| ) | |
| func main() { | |
| sso.Configure( | |
| "sk_example_123456789", | |
| "client_123456789", | |
| ) | |
| connection, err := sso.GetConnection( | |
| context.Background(), | |
| sso.GetConnectionOpts{ | |
| Connection: "conn_01E4ZCR3C56J083X43JQXF3JK5", | |
| }, | |
| ) | |
| } |
| <?php | |
| WorkOS\WorkOS::setApiKey("sk_example_123456789"); | |
| WorkOS\WorkOS::setClientId("client_123456789"); | |
| $sso = new WorkOS\SSO(); | |
| $connection = $sso->getConnection("conn_01E4ZCR3C56J083X43JQXF3JK5"); |
| import com.workos.WorkOS; | |
| import com.workos.sso.models.Connection; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| String connectionId = "conn_01E4ZCR3C56J083X43JQXF3JK5"; | |
| Connection connection = workos.sso.getConnection(connectionId); |
| WorkOS.SetApiKey("sk_example_123456789"); | |
| var ssoService = new SSOService(); | |
| var connection = await ssoService.GetConnection("conn_01E4ZCR3C56J083X43JQXF3JK5"); |
| { | |
| "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" | |
| } | |
| ], | |
| "options": { | |
| "signing_cert": null | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/connectionsParameters Returns Get a list of all of your existing connections matching the criteria specified.
curl "https://api.workos.com/connections" \ --header "Authorization: Bearer sk_example_123456789"
{ "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" } ], "options": { "signing_cert": null }, "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" } ], "list_metadata": { "before": "conn_01HXYZ123456789ABCDEFGHIJ", "after": "conn_01HXYZ987654321KJIHGFEDCBA" } }
| 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.key = "sk_example_123456789" | |
| end | |
| connections = WorkOS::SSO.list_connections |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| connections = workos_client.sso.list_connections() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v3/pkg/sso" | |
| ) | |
| func main() { | |
| sso.Configure( | |
| "sk_example_123456789", | |
| "client_123456789", | |
| ) | |
| list, err := sso.ListConnections( | |
| context.Background(), | |
| sso.ListConnectionsOpts{}, | |
| ) | |
| } |
| <?php | |
| WorkOS\WorkOS::setApiKey("sk_example_123456789"); | |
| WorkOS\WorkOS::setClientId("client_123456789"); | |
| $sso = new WorkOS\SSO(); | |
| [$before, $after, $connections] = $sso->listConnections(); |
| import com.workos.WorkOS; | |
| import com.workos.sso.models.ConnectionList; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| ConnectionList connectionList = workos.sso.listConnections(); |
| WorkOS.SetApiKey("sk_example_123456789"); | |
| var ssoService = new SSOService(); | |
| var connectionList = await ssoService.ListConnections(); |
| { | |
| "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" | |
| } | |
| ], | |
| "options": { | |
| "signing_cert": null | |
| }, | |
| "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/connectionsParameters Returns objectPermanently deletes an existing connection. It cannot be undone.
curl --request DELETE \ --url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \ --header "Authorization: Bearer sk_example_123456789"
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4');
require "workos" WorkOS.configure do |config| config.key = "sk_example_123456789" end WorkOS::SSO.delete_connection( id: "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4" )
from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) workos_client.sso.delete_connection(connection_id="conn_01E2NPPCT7XQ2MVVYDHWGK1WN4")
package main import ( "context" "github.com/workos/workos-go/v3/pkg/sso" ) func main() { sso.Configure( "sk_example_123456789", "client_123456789", ) err := sso.DeleteConnection( context.Background(), sso.DeleteConnectionOpts{ Connection: "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4", }, ) }
<?php WorkOS\WorkOS::setApiKey("sk_example_123456789"); WorkOS\WorkOS::setClientId("client_123456789"); $sso = new WorkOS\SSO(); $sso->deleteConnection("conn_01E2NPPCT7XQ2MVVYDHWGK1WN4");
import com.workos.WorkOS; WorkOS workos = new WorkOS("secretKey"); String connectionId = "conn_01E4ZCR3C56J083X43JQXF3JK5"; workos.sso.deleteConnection(connectionId);
WorkOS.SetApiKey("sk_example_123456789"); var ssoService = new SSOService(); await ssoService.DeleteConnection("conn_01E2NPPCT7XQ2MVVYDHWGK1WN4");
DELETE/connectionsParameters Returns