<!-- llms.txt: https://workos.com/llms.txt -->

# Connection

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](https://workos.com/docs/glossary/oauth-2-0) and [SAML](https://workos.com/docs/glossary/saml).

See the [events reference](https://workos.com/docs/events/connection) documentation for the connection events.

## Create a Connection

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.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

## Delete a Connection

Permanently deletes an existing connection. It cannot be undone.

:::code-group{title="Request"}

```bash language="curl"
curl --request DELETE \
  --url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4');
```

```rb language="ruby"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.sso.delete_connection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5")
```

```py language="python"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.sso.delete_connection(id_="conn_01E4ZCR3C56J083X43JQXF3JK5")
```

```go language="go"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.SSO().DeleteConnection(context.Background(), "conn_01E4ZCR3C56J083X43JQXF3JK5")
	if err != nil {
		panic(err)
	}
}
```

```php language="php"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->sso()->deleteConnection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```java language="java"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.sso.deleteConnection("conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```cs language="dotnet"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.SSO.DeleteConnectionAsync("conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```rust language="rust"
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()
        .delete_connection("conn_01E4ZCR3C56J083X43JQXF3JK5")
        .await?;

    Ok(())
}
```

:::

## Get a Connection

Get the details of an existing connection.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/connections/conn_01E4ZCR3C56J083X43JQXF3JK5" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const connection = await workos.sso.getConnection(
  'conn_01E4ZCR3C56J083X43JQXF3JK5',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.sso.get_connection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.sso.get_connection(id_="conn_01E4ZCR3C56J083X43JQXF3JK5")
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->sso()->getConnection(id: "conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.sso.getConnection("conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.SSO.GetConnectionAsync("conn_01E4ZCR3C56J083X43JQXF3JK5");
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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 Connections

Get a list of all of your existing connections matching the criteria specified.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/connections" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const connectionList = await workos.sso.listConnections();

console.log(connectionList.data);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.sso.list_connections
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.sso.list_connections()
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->sso()->listConnections();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.sso.listConnections();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.SSO.ListConnectionsAsync();
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
  }
}
```

:::

## Update a Connection

Updates an existing connection. Only the provided fields are changed; fields that accept `null` are reset to their default behavior.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### connection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "connection" | Yes | Distinguishes the Connection object. |
| `id` | string | Yes | Unique identifier for the Connection. |
| `organization_id` | string | No | Unique identifier for the Organization in which the Connection resides. |
| `connection_type` | "Pending" \| "ADFSSAML" \| "AdpOidc" \| ... | Yes | The type of the SSO Connection used to authenticate the user. The Connection type may be used to dynamically generate authorization URLs. Possible values: `ADFSSAML` `AdpOidc` `AppleOAuth` `Auth0SAML` `AzureSAML` `CasSAML` `ClassLinkSAML` `CloudflareSAML` `CyberArkSAML` `DuoSAML` `GenericOIDC` `GenericSAML` `GitHubOAuth` `GoogleOAuth` `GoogleSAML` `JumpCloudSAML` `KeycloakSAML` `LastPassSAML` `LoginGovOidc` `MagicLink` `MicrosoftOAuth` `MiniOrangeSAML` `NetIqSAML` `OktaSAML` `OneLoginSAML` `OracleSAML` `PingFederateSAML` `PingOneSAML` `RipplingSAML` `SalesforceSAML` `ShibbolethGenericSAML` `ShibbolethSAML` `SimpleSamlPhpSAML` `VMwareSAML` |
| `name` | string | Yes | A human-readable name for the Connection. This will most commonly be the organization's name. |
| `state` | "requires_type" \| "draft" \| "active" \| ... | Yes | Indicates whether a Connection is able to authenticate users. |
| `status` | "linked" \| "unlinked" | Yes | Deprecated. Use `state` instead. |
| `domains` | object[] | Yes | List of [Organization Domains](/reference/domain-verification). |
| `created_at` | string | Yes | The timestamp when the Connection was created. |
| `updated_at` | string | Yes | The timestamp when the Connection was last updated. |

### POST /connections

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | Unique identifier for the Organization in which the Connection resides. |
| `name` | string | No | A human-readable name for the Connection. This will most commonly be the organization's name. |
| `external_id` | string | No | The customer-owned identifier for the Connection. |
| `connection_type` | string | No | The type of the Connection. Only SAML and OIDC connection types may be created. When omitted, the type is inferred from the provided options. |
| `attribute_maps` | object | No | How IdP attributes or claims map onto WorkOS profile fields. Provided fields override the defaults for the connection type. |
| `saml_options` | object | No | Protocol configuration for SAML connections. Mutually exclusive with `oidc_options`. |
| `oidc_options` | object | No | Protocol configuration for OIDC connections. Mutually exclusive with `saml_options`. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connection` | object | Distinguishes the Connection object. |

### DELETE /connections/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Connection. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### GET /connections/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Connection. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connection` | object | Distinguishes the Connection object. |

### GET /connections

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Defaults to `normal`. |
| `connection_type` | "ADFSSAML" \| "AdpOidc" \| "AppleOAuth" \| ... | No | Filter Connections by their type. |
| `domain` | string | No | Filter Connections by their associated domain. |
| `organization_id` | string | No | Filter Connections by their associated organization. |
| `search` | string | No | Searchable text to match against Connection names. |

### PATCH /connections/{id}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | A human-readable name for the Connection. |
| `external_id` | string | No | The customer-owned identifier for the Connection. Set to `null` to stop tracking one. |
| `connection_type` | string | No | The type of the Connection. Immutable after creation — it may be sent, but only with the Connection current type. |
| `attribute_maps` | object | No | How IdP attributes or claims map onto WorkOS profile fields. Only the provided fields are updated. |
| `saml_options` | object | No | Protocol configuration for SAML connections. Only the provided fields are updated. Mutually exclusive with `oidc_options`. |
| `oidc_options` | object | No | Protocol configuration for OIDC connections. Only the provided fields are updated. Mutually exclusive with `saml_options`. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Connection. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connection` | object | Distinguishes the Connection object. |