Add SamlConnection API to Backend SDK

docs/manifest.json

@@ -2168,6 +2168,39 @@
                       ]
                     ]
                   },
+                  {
+                    "title": "SAML connections",
+                    "collapse": true,
+                    "items": [
+                      [
+                        {
+                          "title": "`getSamlConnectionList()`",
+                          "wrap": false,
+                          "href": "/docs/references/backend/saml-connections/get-saml-connection-list"
+                        },
+                        {
+                          "title": "`getSamlConnection()`",
+                          "wrap": false,
+                          "href": "/docs/references/backend/saml-connections/get-saml-connection"
+                        },
+                        {
+                          "title": "`createSamlConnection()`",
+                          "wrap": false,
+                          "href": "/docs/references/backend/saml-connections/create-saml-connection"
+                        },
+                        {
+                          "title": "`updateSamlConnection()`",
+                          "wrap": false,
+                          "href": "/docs/references/backend/saml-connections/update-saml-connection"
+                        },
+                        {
+                          "title": "`deleteSamlConnection()`",
+                          "wrap": false,
+                          "href": "/docs/references/backend/saml-connections/delete-saml-connection"
+                        }
+                      ]
+                    ]
+                  },
                   {
                     "title": "Testing Tokens",
                     "collapse": true,

docs/references/backend/saml-connections/create-saml-connection.mdx

@@ -0,0 +1,74 @@
+---
+title: createSamlConnection()
+description: Use Clerk's Backend SDK to create a SAML connection.
+---
+
+# `createSamlConnection()`
+
+Creates a new [`SamlConnection`](/docs/references/backend/types/saml-connection).
+
+```tsx
+function createSamlConnection: (params: CreateSamlConnectionParams) => Promise<SamlConnection>;
+```
+
+## `CreateSamlConnectionParams`
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The name to use as a label for this SAML Connection. |
+| `provider` | `'saml_custom' \| 'saml_okta' \| 'saml_google' \| 'saml_microsoft'` | The Identity Provider (IdP) provider of the connection. |
+| `domain` | `string` | The domain of your organization. Sign in flows using an email with this domain will use this SAML Connection. For example: `'clerk.dev'` |
+| `idpEntityId?` | `string` | The Entity ID as provided by the Identity Provider (IdP). |
+| `idpSsoUrl?` | `string` | The Single-Sign On URL as provided by the Identity Provider (IdP). |
+| `idpCertificate?` | `string` | The X.509 certificate as provided by the Identity Provider (IdP). |
+| `idpMetadataUrl?` | `string` | The URL which serves the Identity Provider (IdP) metadata. If present, it takes priority over the corresponding individual properties. |
+| `idpMetadata?` | `string` | The XML content of the Identity Provider (IdP) metadata file. If present, it takes priority over the corresponding individual properties. |
+| `attributeMapping?` | `{ emailAddress?: string, firstName?: string, lastName?: string, userId?: string }` | The attribute mapping for the SAML connection. |
+
+## Example
+
+```tsx
+const response = await clerkClient.samlConnections.createSamlConnection({
+  name: 'test-okta',
+  provider: 'saml_okta',
+  domain: 'clerk.dev',
+  idpMetadataUrl:
+    'https://trial-000000.okta.com/app/exk...',
+  attributeMapping: {
+    emailAddress: 'user.email',
+    firstName: 'user.firstName',
+    lastName: 'user.lastName',
+  },
+});
+
+console.log(response);
+/*
+{
+  object: 'saml_connection',
+  id: 'samlc_123',
+  name: 'test-okta',
+  domain: 'clerk.dev',
+  idp_entity_id: 'http://www.okta.com/exk...',
+  idp_sso_url: 'https://trial-000000.okta.com/app/trial-000000_clerkdocstest_1/exk.../sso/saml',
+  idp_certificate: 'MII...',
+  idp_metadata_url: 'https://trial-000000.okta.com/app/exk.../sso/saml/metadata',
+  idp_metadata: null,
+  acs_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/acs/samlc_123',
+  sp_entity_id: 'https://prepared-phoenix-00.clerk.accounts.dev/saml/samlc_123',
+  sp_metadata_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/metadata/samlc_123.xml',
+  attribute_mapping: { user_id: '', email_address: '', first_name: '', last_name: '' },
+  active: false,
+  provider: 'saml_okta',
+  user_count: 0,
+  sync_user_attributes: true,
+  allow_subdomains: false,
+  allow_idp_initiated: false,
+  created_at: 1720032705432,
+  updated_at: 1720032705432
+}
+*/
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `POST/saml_connections`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/SAML-Connections#operation/CreateSAMLConnection) for more details.

docs/references/backend/saml-connections/delete-saml-connection.mdx

@@ -0,0 +1,40 @@
+---
+title: deleteSamlConnection()
+description: Use Clerk's Backend SDK to delete a SAML connection.
+---
+
+# `deleteSamlConnection()`
+
+Deletes a [`SamlConnection`](/docs/references/backend/types/saml-connection) by its ID.
+
+```tsx
+function deleteSamlConnection: (samlConnectionId: string) => Promise<Organization>;
+```
+
+## Parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `samlConnectionId` | `string` | The ID of the SAML connection to delete. |
+
+## Example
+
+```tsx
+const samlConnectionId = 'samlc_123';
+
+const response = await clerkClient.samlConnections.deleteSamlConnection(samlConnectionId);
+
+console.log(response);
+/*
+_DeletedObject {
+  object: 'saml_connection',
+  id: 'samlc_123',
+  slug: null,
+  deleted: true
+}
+*/
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `DELETE/saml_connections/{saml_connection_id}`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/SAML-Connections#operation/DeleteSAMLConnection) for more details.

docs/references/backend/saml-connections/get-saml-connection-list.mdx

@@ -0,0 +1,89 @@
+---
+title: getSamlConnectionList()
+description: Use Clerk's Backend SDK to retrieve the list of SAML connections for an instance.
+---
+
+# `getSamlConnectionList()`
+
+Retrieves the list of SAML connections for an instance.
+
+```tsx
+function getSamlConnectionList: (params: SamlConnectionListParams = {}) => Promise<SamlConnection[]>;
+```
+
+## `SamlConnectionListParams`
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `limit?` | `number` | The number of results to return. Must be an integer greater than zero and less than 501. Default: `10` |
+| `offset?` | `number` | The number of results to skip. Default: `0` |
+
+## Examples
+
+### Basic
+
+In this example, you can see that the returned response includes `data`, which is an array of [`SamlConnection`](/docs/references/backend/types/saml-connection) objects, and `totalCount`, which indicates the total number of connections.
+
+While the response can return up to 10 data items, for the sake of brevity, only one is shown in this example response.
+
+```tsx
+const response = await clerkClient.samlConnections.getSamlConnectionList();
+
+console.log(response);
+/*
+{
+  data: [
+    {
+      object: 'saml_connection',
+      id: 'samlc_123',
+      name: 'test-okta',
+      domain: 'clerk.dev',
+      idp_entity_id: 'http://www.okta.com/exk...',
+      idp_sso_url: 'https://trial-000000.okta.com/app/trial-000000_clerkdocstest_1/exk.../sso/saml',
+      idp_certificate: 'MII...',
+      idp_metadata_url: 'https://trial-000000.okta.com/app/exk.../sso/saml/metadata',
+      idp_metadata: null,
+      acs_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/acs/samlc_123',
+      sp_entity_id: 'https://prepared-phoenix-00.clerk.accounts.dev/saml/samlc_123',
+      sp_metadata_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/metadata/samlc_123.xml',
+      attribute_mapping: { user_id: '', email_address: '', first_name: '', last_name: '' },
+      active: false,
+      provider: 'saml_okta',
+      user_count: 0,
+      sync_user_attributes: true,
+      allow_subdomains: false,
+      allow_idp_initiated: false,
+      created_at: 1720032705432,
+      updated_at: 1720032705432
+    }
+  ],
+  totalCount: 1
+}
+*/
+```
+
+### Limit the number of results
+
+Retrieves organization list that is filtered by the number of results.
+
+```tsx
+const { data, totalCount } = await clerkClient.samlConnections.getSamlConnectionList({
+  // returns the first 10 results
+  limit: 10,
+});
+```
+
+### Skip results
+
+Retrieves organization list that is filtered by the number of results to skip.
+
+```tsx
+const { data, totalCount } = await clerkClient.samlConnections.getSamlConnectionList({
+  // skips the first 10 results
+  offset: 10,
+});
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `GET/saml_connections`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/SAML-Connections#operation/ListSAMLConnections) for more details.

docs/references/backend/saml-connections/get-saml-connection.mdx

@@ -0,0 +1,57 @@
+---
+title: getSamlConnection()
+description: Use Clerk's Backend SDK to retrieve a SAML connection.
+---
+
+# `getSamlConnection()`
+
+Retrieves a [`SamlConnection`](/docs/references/backend/types/saml-connection) by its ID.
+
+```tsx
+function getSamlConnection: (samlConnectionId: string) => Promise<SamlConnection>;
+```
+
+## `GetOrganizationParams`
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `samlConnectionId` | `string` | The ID of the SAML connection to retrieve. |
+
+## Example
+
+```tsx
+const samlConnectionId = 'samlc_123';
+
+const response = await clerkClient.samlConnections.getSamlConnection(samlConnectionId);
+
+console.log(response);
+/*
+{
+  object: 'saml_connection',
+  id: 'samlc_123',
+  name: 'test-okta',
+  domain: 'clerk.dev',
+  idp_entity_id: 'http://www.okta.com/exk...',
+  idp_sso_url: 'https://trial-000000.okta.com/app/trial-000000_clerkdocstest_1/exk.../sso/saml',
+  idp_certificate: 'MII...',
+  idp_metadata_url: 'https://trial-000000.okta.com/app/exk.../sso/saml/metadata',
+  idp_metadata: null,
+  acs_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/acs/samlc_123',
+  sp_entity_id: 'https://prepared-phoenix-00.clerk.accounts.dev/saml/samlc_123',
+  sp_metadata_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/metadata/samlc_123.xml',
+  attribute_mapping: { user_id: '', email_address: '', first_name: '', last_name: '' },
+  active: false,
+  provider: 'saml_okta',
+  user_count: 0,
+  sync_user_attributes: true,
+  allow_subdomains: false,
+  allow_idp_initiated: false,
+  created_at: 1720032705432,
+  updated_at: 1720032705432
+}
+*/
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `GET/saml_connections/{saml_connection_id}`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/SAML-Connections#operation/GetSAMLConnection) for more details.

docs/references/backend/saml-connections/update-saml-connection.mdx

@@ -0,0 +1,74 @@
+---
+title: updateSamlConnection()
+description: Use Clerk's Backend SDK to update a SAML connection.
+---
+
+# `updateSamlConnection()`
+
+Updates a [`SamlConnection`](/docs/references/backend/types/saml-connection) by its ID.
+
+```tsx
+function updateSamlConnection: (samlConnectionId: string, params: UpdateSamlConnectionParams = {}) => Promise<Organization>;
+```
+
+## `UpdateSamlConnectionParams`
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `name?` | `string` | The name to use as a label for this SAML Connection. |
+| `provider?` | `'saml_custom' \| 'saml_okta' \| 'saml_google' \| 'saml_microsoft'` | The IdP provider of the connection. |
+| `domain?` | `string` | The domain of your organization. Sign in flows using an email with this domain will use this SAML Connection. For example: `'clerk.dev'` |
+| `idpEntityId?` | `string` | The Entity ID as provided by the IdP. |
+| `idpSsoUrl?` | `string` | The Single-Sign On URL as provided by the IdP. |
+| `idpCertificate?` | `string` | The X.509 certificate as provided by the IdP. |
+| `idpMetadataUrl?` | `string` | The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties. |
+| `idpMetadata?` | `string` | The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties. |
+| `attributeMapping?` | `{ emailAddress?: string, firstName?: string, lastName?: string, userId?: string }` | The attribute mapping for the SAML connection. |
+| `active?` | `boolean` | Indicates whether the connection is active or not. |
+| `syncUserAttributes?` | `boolean` | Indicates whether the connection syncs user attributes between the Service Provider (SP) and Identity Provider (IdP) or not. |
+| `allowSubdomains?` | `boolean` | Indicates whether users with an email address subdomain are allowed to use this connection in order to authenticate or not. |
+| `allowIdpInitiated?` | `boolean` | Indicates whether the connection allows Identity Provider (IdP) initiated flows or not. |
+
+## Example
+
+In this example, the name of the SAML connection is updated.
+
+```tsx {{ mark: [[3,6], 13]}}
+const samlConnectionId = 'samlc_123';
+
+const response = await clerkClient.samlConnections.updateSamlConnection(
+  samlConnectionId,
+  { name: 'Updated SAML Connection' }
+);
+
+console.log(response);
+/*
+{
+  object: 'saml_connection',
+  id: 'samlc_123',
+  name: 'Updated SAML Connection',
+  domain: 'clerk.dev',
+  idp_entity_id: 'http://www.okta.com/exk...',
+  idp_sso_url: 'https://trial-000000.okta.com/app/trial-000000_clerkdocstest_1/exk.../sso/saml',
+  idp_certificate: 'MII...',
+  idp_metadata_url: 'https://trial-000000.okta.com/app/exk.../sso/saml/metadata',
+  idp_metadata: null,
+  acs_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/acs/samlc_123',
+  sp_entity_id: 'https://prepared-phoenix-00.clerk.accounts.dev/saml/samlc_123',
+  sp_metadata_url: 'https://prepared-phoenix-00.clerk.accounts.dev/v1/saml/metadata/samlc_123.xml',
+  attribute_mapping: { user_id: '', email_address: '', first_name: '', last_name: '' },
+  active: false,
+  provider: 'saml_okta',
+  user_count: 0,
+  sync_user_attributes: true,
+  allow_subdomains: false,
+  allow_idp_initiated: false,
+  created_at: 1720032705432,
+  updated_at: 1720032705432
+}
+*/
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `PATCH/saml_connections/{saml_connection_id}`. See the [BAPI reference](https://clerk.com/docs/reference/backend-api/tag/SAML-Connections#operation/UpdateSAMLConnection) for more details.