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

# Single Sign-On

Manage the SSO connections of the organization the token was issued for.

## Create an SSO connection

Create an SSO connection for the token's organization.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation CreateSsoConnection($input: CreateSsoConnectionInput!) {
  createSsoConnection(input: $input) {
    createdAt
    id
    lastSession {
      createdAt
      id
      state
    }
    latestExpiredCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    latestExpiringCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    name
    organizationId
    providerTag
    setupComplete
    state
    type
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "createSsoConnection": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "lastSession": null,
      "latestExpiredCertificate": null,
      "latestExpiringCertificate": null,
      "name": "name_example",
      "organizationId": "organizationId_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "providerTag": "Saml",
      "setupComplete": false,
      "state": "Inactive",
      "type": "ADFSSAML",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## Delete an SSO connection

Delete an SSO connection belonging to the token's organization.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation DeleteSsoConnection($id: ID!) {
  deleteSsoConnection(id: $id)
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "deleteSsoConnection": "deleteSsoConnection_01EHWNCE74X7JSDV0X3SZ3KJNY"
  }
}
```

:::

## Get an SSO connection

Returns an SSO connection by ID, including its IdP setup status, provided it belongs to the token's organization.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query SsoConnection($id: ID!) {
  ssoConnection(id: $id) {
    createdAt
    id
    lastSession {
      createdAt
      id
      state
    }
    latestExpiredCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    latestExpiringCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    name
    organizationId
    providerTag
    setupComplete
    state
    type
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "ssoConnection": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "lastSession": {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "state": "Authorized"
      },
      "latestExpiredCertificate": null,
      "latestExpiringCertificate": {
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "lastExpiryEventSentAt": "2024-01-01T00:00:00.000Z",
        "notAfter": "2024-01-01T00:00:00.000Z",
        "notBefore": "2024-01-01T00:00:00.000Z",
        "value": "value_example"
      },
      "name": "name_example",
      "organizationId": "organizationId_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "providerTag": "Saml",
      "setupComplete": true,
      "state": "Active",
      "type": "ADFSSAML",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

## List SSO connections

List the SSO connections belonging to the organization the token was issued for.

:::code-group

```graphql language="graphql" title="Query" tab="1"
query SsoConnections {
  ssoConnections {
    createdAt
    id
    lastSession {
      createdAt
      id
      state
    }
    latestExpiredCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    latestExpiringCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    name
    organizationId
    providerTag
    setupComplete
    state
    type
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "ssoConnections": [
      {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "lastSession": {
          "createdAt": "2024-01-01T00:00:00.000Z",
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "state": "Authorized"
        },
        "latestExpiredCertificate": null,
        "latestExpiringCertificate": {
          "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
          "lastExpiryEventSentAt": "2024-01-01T00:00:00.000Z",
          "notAfter": "2024-01-01T00:00:00.000Z",
          "notBefore": "2024-01-01T00:00:00.000Z",
          "value": "value_example"
        },
        "name": "name_example",
        "organizationId": "organizationId_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "providerTag": "Saml",
        "setupComplete": true,
        "state": "Active",
        "type": "ADFSSAML",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

:::

## Update an SSO connection

Update an SSO connection belonging to the token's organization.

:::code-group

```graphql language="graphql" title="Mutation" tab="1"
mutation UpdateSsoConnection($input: UpdateSsoConnectionInput!) {
  updateSsoConnection(input: $input) {
    createdAt
    id
    lastSession {
      createdAt
      id
      state
    }
    latestExpiredCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    latestExpiringCertificate {
      id
      lastExpiryEventSentAt
      notAfter
      notBefore
      value
    }
    name
    organizationId
    providerTag
    setupComplete
    state
    type
    updatedAt
  }
}
```

```json language="json" title="Response" tab="2"
{
  "data": {
    "updateSsoConnection": {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "lastSession": {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "state": "Authorized"
      },
      "latestExpiredCertificate": null,
      "latestExpiringCertificate": {
        "id": "id_01EHWNCE74X7JSDV0X3SZ3KJNY",
        "lastExpiryEventSentAt": "2024-01-01T00:00:00.000Z",
        "notAfter": "2024-01-01T00:00:00.000Z",
        "notBefore": "2024-01-01T00:00:00.000Z",
        "value": "value_example"
      },
      "name": "name_example",
      "organizationId": "organizationId_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "providerTag": "Saml",
      "setupComplete": true,
      "state": "Active",
      "type": "ADFSSAML",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

:::

### Mutation createSsoConnection

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | String | No | A human-readable name for the connection. Defaults to the organization's name. |
| `type` | ConnectionType! | Yes | The identity provider type of the connection to create. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `lastSession` | SsoConnectionSession | The most recent sign-in session through this connection, if any. |
| `latestExpiredCertificate` | X509Certificate | The most recently expired SAML certificate when the connection has no valid certificate left, if any. Always null for OpenID Connect connections. |
| `latestExpiringCertificate` | X509Certificate | The connection's longest-lived unexpired SAML certificate when it expires within the next three months, if any. Null when a certificate valid beyond that window exists. Always null for OpenID Connect connections. |
| `name` | String! | A human-readable name for the connection. |
| `organizationId` | ID | The organization the connection belongs to. |
| `providerTag` | SsoProviderTag! | Whether the connection speaks SAML or OpenID Connect. |
| `setupComplete` | Boolean! | Whether the connection has completed its IdP setup and can authenticate users (equivalent to an `Active` state). |
| `state` | ConnectionState! | The connection's IdP setup status. `Active` indicates setup is complete; other states indicate where the connection is in its setup flow. |
| `type` | ConnectionType! | The identity provider type of the connection. |
| `updatedAt` | DateTime! |  |

### Mutation deleteSsoConnection

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `deleteSsoConnection` | ID! |  |

### Query ssoConnection

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `lastSession` | SsoConnectionSession | The most recent sign-in session through this connection, if any. |
| `latestExpiredCertificate` | X509Certificate | The most recently expired SAML certificate when the connection has no valid certificate left, if any. Always null for OpenID Connect connections. |
| `latestExpiringCertificate` | X509Certificate | The connection's longest-lived unexpired SAML certificate when it expires within the next three months, if any. Null when a certificate valid beyond that window exists. Always null for OpenID Connect connections. |
| `name` | String! | A human-readable name for the connection. |
| `organizationId` | ID | The organization the connection belongs to. |
| `providerTag` | SsoProviderTag! | Whether the connection speaks SAML or OpenID Connect. |
| `setupComplete` | Boolean! | Whether the connection has completed its IdP setup and can authenticate users (equivalent to an `Active` state). |
| `state` | ConnectionState! | The connection's IdP setup status. `Active` indicates setup is complete; other states indicate where the connection is in its setup flow. |
| `type` | ConnectionType! | The identity provider type of the connection. |
| `updatedAt` | DateTime! |  |

### Query ssoConnections

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `lastSession` | SsoConnectionSession | The most recent sign-in session through this connection, if any. |
| `latestExpiredCertificate` | X509Certificate | The most recently expired SAML certificate when the connection has no valid certificate left, if any. Always null for OpenID Connect connections. |
| `latestExpiringCertificate` | X509Certificate | The connection's longest-lived unexpired SAML certificate when it expires within the next three months, if any. Null when a certificate valid beyond that window exists. Always null for OpenID Connect connections. |
| `name` | String! | A human-readable name for the connection. |
| `organizationId` | ID | The organization the connection belongs to. |
| `providerTag` | SsoProviderTag! | Whether the connection speaks SAML or OpenID Connect. |
| `setupComplete` | Boolean! | Whether the connection has completed its IdP setup and can authenticate users (equivalent to an `Active` state). |
| `state` | ConnectionState! | The connection's IdP setup status. `Active` indicates setup is complete; other states indicate where the connection is in its setup flow. |
| `type` | ConnectionType! | The identity provider type of the connection. |
| `updatedAt` | DateTime! |  |

### Mutation updateSsoConnection

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | ID! | Yes |  |
| `name` | String | No | A new human-readable name for the connection. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | DateTime! |  |
| `id` | ID! |  |
| `lastSession` | SsoConnectionSession | The most recent sign-in session through this connection, if any. |
| `latestExpiredCertificate` | X509Certificate | The most recently expired SAML certificate when the connection has no valid certificate left, if any. Always null for OpenID Connect connections. |
| `latestExpiringCertificate` | X509Certificate | The connection's longest-lived unexpired SAML certificate when it expires within the next three months, if any. Null when a certificate valid beyond that window exists. Always null for OpenID Connect connections. |
| `name` | String! | A human-readable name for the connection. |
| `organizationId` | ID | The organization the connection belongs to. |
| `providerTag` | SsoProviderTag! | Whether the connection speaks SAML or OpenID Connect. |
| `setupComplete` | Boolean! | Whether the connection has completed its IdP setup and can authenticate users (equivalent to an `Active` state). |
| `state` | ConnectionState! | The connection's IdP setup status. `Active` indicates setup is complete; other states indicate where the connection is in its setup flow. |
| `type` | ConnectionType! | The identity provider type of the connection. |
| `updatedAt` | DateTime! |  |