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

# SP Encryption Certificate

:::code-group{title="Example SamlSpEncryptionCertificate"}

```json language="curl"
{
  "object": "saml_sp_encryption_certificate",
  "id": "saml_enc_key_pair_01E4ZCR3C56J083X43JQXF3JK5",
  "value": "-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----",
  "not_before": "2026-01-15T12:00:00.000Z",
  "not_after": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Create an SP encryption certificate

Generates a new encryption key pair for the connection and returns its public certificate. WorkOS holds the private key, so the request takes no body — to bring your own key pairs, provide `saml_options.sp_encryption_key_pairs` when creating the connection instead. Creating a certificate appends rather than replaces: every active private key is tried when decrypting, which lets a rotation overlap the old and new certificates.

:::code-group

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

```json language="json" title="Response" tab="2"
{
  "object": "saml_sp_encryption_certificate",
  "id": "saml_enc_key_pair_01E4ZCR3C56J083X43JQXF3JK5",
  "value": "-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----",
  "not_before": "2026-01-15T12:00:00.000Z",
  "not_after": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Delete an SP encryption certificate

Removes an encryption key pair from the connection. SAML responses encrypted with its certificate can no longer be decrypted, so remove the certificate from the Identity Provider first when rotating.

:::code-group

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

:::

## List SP encryption certificates

Lists the public certificates the Identity Provider can use to encrypt SAML responses sent to WorkOS, including expired ones, oldest first.

:::code-group

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

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "saml_sp_encryption_certificate",
      "id": "saml_enc_key_pair_01E4ZCR3C56J083X43JQXF3JK5",
      "value": "-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----",
      "not_before": "2026-01-15T12:00:00.000Z",
      "not_after": "2026-01-15T12:00:00.000Z",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

:::

### saml_sp_encryption_certificate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "saml_sp_encryption_certificate" | Yes | Distinguishes the SAML Service Provider encryption certificate object. |
| `id` | string | Yes | Unique identifier for the Service Provider encryption key pair. WorkOS holds the corresponding private key, which is never exposed. |
| `value` | string | Yes | The PEM-encoded public X.509 certificate. |
| `not_before` | string | No | When the certificate becomes valid. |
| `not_after` | string | No | When the certificate expires. |
| `created_at` | string | Yes | An ISO 8601 timestamp. |

### POST /connections/{connectionId}/saml_sp_encryption_certs

#### Parameters

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

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `saml_sp_encryption_certificate` | object | Distinguishes the SAML Service Provider encryption certificate object. |

### DELETE /connections/{connectionId}/saml_sp_encryption_certs/{certificateId}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionId` | string | Yes | Unique identifier for the Connection. |
| `certificateId` | string | Yes | Unique identifier for the Service Provider encryption key pair. WorkOS holds the corresponding private key, which is never exposed. |

#### Returns

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

### GET /connections/{connectionId}/saml_sp_encryption_certs

#### Parameters

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

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `list` | object |  |